Skip to content
Docs menu

Write a plugin

Scaffold, write, test and publish a venom plugin with tools, commands, leader keys, block renderers, HUD fields and panel sections.

View .md

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 project

There 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:

  1. venom-plugin.json;
  2. package.json with a venom key and/or pi's pi key (venom wins key by key);
  3. .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 session

The 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/or pi) key. Keep pi's packages (@earendil-works/pi-*, typebox) as peerDependencies: "*", since the host provides them. Add the keywords venom-plugin and pi-package. Users run venom 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 permissions is not enforced at run time.
  • Subagents do not load plugin extensions; a plugin's agents are available to the main agent's task tool.
  • 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.