Write a plugin
Scaffold, write, test and publish a venom plugin with tools, commands, leader keys, block renderers, HUD fields and panel sections.
A plugin's code is a pi extension: a module whose default export receives pi's ExtensionAPI. venom wraps it in a small SDK (@venom/harness/plugin) that adds leader keys, block renderers, HUD fields, panel sections, typed config and event watchers. The author's reference in the repository is docs/plugins.md; this page covers the same ground.
Quick start
venom plugin new hello # a TypeScript plugin: a tool, a command, a test, a README
cd hello && npm test # node --test, nothing to install
venom plugin dev . # a session with it loaded; edit src/, then /reload
venom plugin add path:$(pwd) # install it for every projectThere is no build step: pi loads TypeScript itself. venom plugin new takes --template:
| Template | What it generates |
|---|---|
tool (default) |
a model-callable tool and a command |
command |
a command and a leader key |
renderer |
a renderer for fenced code blocks of its own language |
panel |
an agents-panel section and a HUD field |
skill |
a SKILL.md and a command |
// src/index.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
import { venom } from "./venom.ts";
export default function hello(pi: ExtensionAPI): void {
const api = venom(pi, { name: "hello", apiVersion: 1 });
api.registerTool({
name: "hello_greet",
label: "hello: greet",
description: "Greet someone by name.",
parameters: Type.Object({ who: Type.String({ description: "Name to greet" }) }),
annotations: { readOnlyHint: true },
async execute(_id, { who }) {
return { content: [{ type: "text", text: `${api.config<{ greeting: string }>().greeting}, ${who}!` }], details: undefined };
},
});
api.registerCommand("hello", { description: "Greet", handler: async (args, ctx) => ctx.ui.notify(`hi ${args}`, "info") });
api.registerLeaderBinding("h", "/hello");
}The generated src/venom.ts reaches the SDK through the host that loaded the plugin, so the plugin needs no runtime dependency. For editor types, install venom's harness tarball as a dev dependency (venom-harness-<v>.tgz from a release) and import type from @venom/harness/plugin. definePlugin(meta, setup) is the same thing as a factory: export default definePlugin({ name: "x" }, (api) => { … }).
The manifest
venom reads, in this order of precedence:
venom-plugin.json;package.jsonwith avenomkey and/or pi'spikey (venomwins key by key);.claude-plugin/plugin.json, a Claude Code plugin.
{
"name": "hello",
"version": "0.1.0",
"type": "module",
"venom": {
"apiVersion": 1,
"extensions": ["./src/index.ts"],
"skills": ["./skills"],
"hooks": "./hooks/hooks.json",
"mcpServers": "./.mcp.json",
"configSchema": { "type": "object", "properties": { "greeting": { "type": "string", "default": "Hello" } }, "additionalProperties": false },
"permissions": { "env": ["HELLO_TOKEN"], "network": ["api.example.com"], "tools": ["hello_greet"] },
"tools": ["hello_greet"],
"keybindings": { "h": "/hello" }
}
}| Key | Default | What |
|---|---|---|
name |
required | lowercase letters, digits, ., _, -, at most 64; @scope/x becomes scope-x. The key of its config and the prefix of its commands. sources is reserved |
version, description |
from package.json |
|
apiVersion |
1 |
the plugin API it targets; newer than venom's means invalid ("upgrade venom") |
extensions |
extensions/*.ts|js and extensions/<dir>/index.ts|js |
pi extension entry files |
skills, commands, agents, prompts, themes |
the directory of that name | Claude Code formats; plugin commands run as /<plugin>:<command> |
roles |
roles/ |
standing agents for venom role add (Plugin roles) |
hooks |
hooks/hooks.json |
a Claude Code hooks file |
mcpServers |
.mcp.json |
a .mcp.json-shaped file. ${VENOM_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_ROOT} expand to the plugin's directory |
configSchema |
none | JSON Schema of plugins.<name>.config; its defaults fill in |
permissions |
none | what the plugin reads (env), contacts (network) and registers (tools). Shown at install and by venom plugin list --json. Declared, not enforced |
tools, renderers, keybindings |
none | declared contributions for listings; keybindings maps a key after the leader to a slash command |
Every path must stay inside the plugin. A manifest with a problem is listed as invalid with the first problem and not loaded.
The API (apiVersion 1)
venom(pi, { name, apiVersion }) returns a VenomPluginAPI:
| Member | What |
|---|---|
pi |
pi's ExtensionAPI for everything else (pi.on, sendMessage, registerProvider, registerMcpServer) |
registerTool, registerCommand, registerShortcut |
pi's. A tool goes through venom's permission gate: annotations.readOnlyHint is allowed in every mode, anything else asks (plan mode denies). Tool results are marked as untrusted content |
registerLeaderBinding(key, "/command") |
a key after the leader (ctrl+g). venom's own keys and the user's keys.leader_bindings win |
registerBlockRenderer(lang | lang[], render) |
draws fenced blocks of that language in the TUI: render(code, { lang, info, width, messageType, streaming }) returns text or undefined (left as written). The model still sees the fence as written |
setHudSegment(ctx, id, text | undefined) |
a field on the HUD status line (plugin:<name>:<id>) |
registerPanelSection(id, title, render(width) → lines) |
a section in the agents panel, at most 6 lines |
config<T>() |
plugins.<name>.config, checked against configSchema, defaults filled; {} outside venom |
onHook(event, handler) |
watch an event; returns an unsubscribe function. Events: session_start, session_end, prompt, turn_done, agent_done, subagent_done, tool_call, tool_done, and harness:<type> for any harness event (harness:compaction, harness:permission, harness:checkpoint). Watchers cannot change the event; use pi.on to block or rewrite |
onCall(listener) |
every model request venom makes: model, tokens, cost, milliseconds |
decisions() |
the typed decision provider, or undefined |
log(message) |
a diagnostic, shown with VENOM_DEBUG=1 |
Renderers, HUD fields, panel sections and leader keys are UI only: they never reach the model, and they do nothing in -p, venom serve and venom acp. Tools, commands, hooks, skills and agents work everywhere.
Idempotency keys for side effects
A tool that pays, files a ticket or deploys can make retries safe:
import { toolIdempotencyKey } from "@venom/harness";
// inside execute(toolCallId, params, signal, onUpdate, ctx)
const key = toolIdempotencyKey(ctx, toolCallId); // "venom-<sha256 hex>", undefined without a sessionThe key hashes only the session id and the tool call id, so a call replayed after venom resume gets the same key. Send it as the service's idempotency header.
Writing tool descriptions
The model reads every tool and parameter description on each request. Keep a tool to one or two sentences (what it does, when to use it, side effects such as network or spending money) and a parameter to a few words with unit and limits ("Timeout, ms (max 120000)"). Put the description on the property itself, not on an optional wrapper.
Locking a tool behind a skill
A deferred plugin or MCP tool can stay locked until a skill loads. List it in the skill's frontmatter:
---
name: gh-flow
description: Open and triage issues.
venom-tools: mcp__gh__create_issue, mcp__gh__*_label
---Until the session loads gh-flow, a call is refused with "load skill gh-flow first". Built-in tools cannot be locked, and permissions still decide.
Generate a plugin from an MCP server or OpenAPI file
venom plugin scaffold --from-mcp github # a stdio server named in your MCP config
venom plugin scaffold --from-mcp "node ./srv.mjs" # or a stdio command (no shell)
venom plugin scaffold --from-openapi ./petstore.yaml --name pets--from-mcp reads each tool's live schema with tools/list and writes one tool per MCP tool that forwards the call over stdio. HTTP and SSE servers are refused. --from-openapi writes one tool per operation from a local OpenAPI 3 file; the tool calls config.baseUrl (default: the file's first server). Generated files start with // GENERATED by venom plugin scaffold …; running the command again rewrites only those. Credentials never go into code: put them in config.headers as {{secret:NAME}}, read from the environment variable NAME when a call runs. A command line that looks like it carries a token is refused.
Check, develop and publish
| Command | What |
|---|---|
venom plugin dev <path> [venom args…] |
a session (TUI or -p) with that plugin loaded; venom says when a file changed and /reload picks it up |
venom plugin check <path> [--json] [--no-write] |
validate the plugin and derive minVenom from the SDK methods it calls; writes venom-plugin.derived.json (ship it). An older venom lists the plugin as invalid |
venom plugin new <name> [--template t] [--dir d] |
scaffold |
venom plugin scaffold --from-mcp … | --from-openapi … [--name n] [--dir d] |
generate |
Publishing:
- npm: publish with the
venom(and/orpi) key. Keep pi's packages (@earendil-works/pi-*,typebox) aspeerDependencies: "*", since the host provides them. Add the keywordsvenom-pluginandpi-package. Users runvenom plugin add npm:<name>@<version>. - git: tag releases; users run
venom plugin add git:github.com/you/plugin@v1. - A directory:
venom plugin add path:<dir>, or drop it into~/.venom/plugins/.
Compatibility
apiVersion is a major version. Within it venom only adds members, events and manifest keys; a removal or a changed meaning is a new apiVersion, and the previous one keeps loading for at least one release. pi's ExtensionAPI belongs to pi; venom pins pi exactly and notes API changes in its changelog.
Limitations
- Plugin code is not sandboxed, and
permissionsis not enforced at run time. - Subagents do not load plugin extensions; a plugin's agents are available to the main agent's
tasktool. - A block renderer draws text in a code block; it cannot change the surrounding Markdown.
- Panel sections and HUD fields render only in the TUI.