pi-delegate

English · 繁體中文

Call a local pi agent from inside Claude Code: Claude writes the task book and judges the result, pi writes the source and the tests.

Claude reads the code and writes the contract; pi_dispatch hands the writing to pi. The rows under the status line are this window's dispatches, one per row, and they disappear when the last one finishes.

Why a plugin rather than a written rule: with the rule in place, roughly 80% of the characters committed to this repo were still typed by the main model. In strict mode a PreToolUse hook denies Claude's own Write and Edit on existing product source and tells it to dispatch instead.

Dispatches go to whatever provider and model your pi is already pointed at; this plugin pins nothing.

That rail has a hole, and it is deliberate: the hook matches Write and Edit only, so the same edit made through Bash (sed -i, a heredoc) is never intercepted. It blocks editing a file yourself out of habit, not a deliberate workaround.

Install

/plugin marketplace add LarryStanley/pi-delegate
/plugin install pi-delegate@pi-delegate

Run both inside Claude Code: the first registers this repository as a plugin marketplace, the second installs the plugin from it. If the install summary says Run /reload-plugins to activate., run that too. Requires Node ≥ 22 and a pi installation that is already set up; dependencies are installed automatically from the committed lockfile, so there is nothing to npm install yourself.

To update later:

/plugin marketplace update pi-delegate

claude --plugin-dir /path/to/pi-delegate

Runs a working copy instead of the published version. A --plugin-dir copy takes precedence over the installed one for that session, so you can test changes without uninstalling.

Then run /pi-delegate:setup: it finds pi and works out which provider and model a dispatch will actually reach, explains the discipline modes and asks which one you want, and fixes what it can. It then offers a verification dispatch and the status line indicator, and closes with what to do next.

Related MCP server: Claude Code Manager WAN

Configuration: nothing is required by default

pi_dispatch specifies no provider or model, so dispatches land on whatever you already point pi at (defaultProvider / defaultModel in ~/.pi/agent/settings.json): anthropic, openai, litellm, ollama, LM Studio, or a local OpenAI-compatible server such as omlx, all the same way. /pi-delegate:doctor tells you which model a dispatch will actually reach, and only raises problems that apply.

The defaults below were measured, not guessed

Pinning a provider and model, the resolution order between call arguments, the config file and pi's own defaults, and which flags are structural rather than yours to override: docs/configuration.md.

Modes

strict blocks Write and Edit, which is not the same as blocking edits — sed -i and a heredoc walk straight past it, and /pi-delegate:probe clears the way for one deliberate hand-edit. What counts as existing product code, where the per-project state lives, and where the holes are: docs/configuration.md.

MCP tools

Consulting pi instead of delegating to it

Everything above hands pi characters you would otherwise type. These two do the opposite: pi writes nothing, and the output is its opinion.

Both are slash commands rather than MCP tools on purpose, because a tool's schema is paid in every context and a skill costs nothing until you invoke it. That reasoning, and the rest of the plumbing decisions, are in docs/design-notes.md.

Dispatching behind a critic gate

/pi-delegate:critique <task> is a normal dispatch with one thing added: the work does not count as done because pi said it was done.

Costs roughly 3-10× a plain dispatch, and against a local endpoint the rounds are serial wall-clock. Worth it where a mistake is expensive to find later (auth, money, migrations, public interfaces, silent failures); not worth it for internal tooling where the feedback loop is "run it and see".

How you learn a dispatch finished

Two channels, and only one of them is a guarantee. pi_status / pi_result — reliable. The MCP server talks to pi over RPC (pi --mode rpc), so it knows the outcome the moment it happens. The completion notification — a convenience. MCP gives a server no way to push a message into a conversation, so the completion goes over a per-session socket to the plugin's monitor, whose stdout Claude Code turns into a notification, and monitors run in interactive CLI sessions only — a headless run has no watcher at all.

The notification used to be a tail -F over a log file, and when the reader died the completions stopped with nothing to say so. What that cost and what replaced it: docs/design-notes.md.

Seeing a dispatch while it runs

/pi-delegate:setup offers this row at step 5; /pi-delegate:statusline adds it later if you declined it there or skipped setup. Either way it is a row on the Claude Code status line that exists only while a pi dispatch is in flight:

● pi   18m22s  Qwen3.8-27B-Instruct-MLX
● pi    7m04s  qwen3-coder-30b

Each row carries its own elapsed time, turning amber at 5 minutes and red at 15 on its own, which is the point of splitting them: one 18-minute dispatch should not drag a 20-second one red alongside it. Installing the row probes whatever status line you already have by running it, and composes rather than replaces. Why the row is bash and not Node, why ownership travels on line 2 of the status file, and what 0.13.0 got wrong by counting every window's dispatches: docs/design-notes.md.

How a dispatch works

Claude never speaks the RPC protocol directly — the MCP server holds the pipe, which is what makes mid-run pi_steer and pi_abort possible.

The MCP server's activation spans the whole session; that's why it can still deliver a steer to the pi child's stdin mid-run, and why it — not the child process — decides when the run is over.

Known gaps

pi_stats only returns the tokens and duration_s already present in the verdict. The get_session_stats passthrough that would also report cost and context usage is not yet built.

Documentation

Claude loads the skills below by itself when the situation calls for one. They are listed so you can read what it will be told; setup, doctor, mode and probe are commands that walk you through something rather than documents to read.

Development

npm test                    # node --test, no external dependencies
claude plugin validate .

fixtures/fake-pi.mjs stands in for pi --mode rpc. It deliberately lives outside test/ — node --test treats any file under **/test/**/*.{cjs,mjs,js} as a test file, and putting it in test/ would add one permanently-passing phantom test.

License

MIT. See LICENSE.