---
title: Write a plugin
description: Scaffold, write, test and publish a venom plugin with tools, commands, leader keys, block renderers, HUD fields and panel sections.
section: plugins
order: 20
audience: [builder, agent]
sources: [docs/plugins.md, packages/harness/src/plugin.ts, packages/harness/src/plugins/manifest.ts, packages/harness/src/plugins/since.ts, cli/src/plugin-command.ts, examples/plugins/hello]
features: [plugins.plugin]
---

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

```bash
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 |

```ts
// 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 {#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](/docs/plugins/claude-code-plugins.md).

```json
{
  "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](/docs/plugins/roles.md)) |
| `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 `default`s 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) {#api}

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

```ts
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:

```yaml
---
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

```bash
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.

## Related

- [Install and manage plugins](/docs/plugins/installing.md)
- [Hooks](/docs/plugins/hooks.md)
- [Skills and commands](/docs/plugins/skills.md)
