pi-delegate-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PI_DELEGATE_MODEL | No | Model used when a call omits `model`. Defaults to pi's own default. Model names must resolve against pi's `enabledModels` scope (custom providers declared in `~/.pi/agent/models.json` bypass the scope unless PI_DELEGATE_STRICT_SCOPE=1). | pi's own default |
| PI_CODING_AGENT_DIR | No | Where pi's `auth.json` and config are read from. | ~/.pi/agent |
| PI_DELEGATE_HISTORY | No | Number of finished sessions kept for review. | 50 |
| PI_DELEGATE_LIST_CAP | No | Above this many models, `init` summarises models by provider instead of listing them. | 60 |
| PI_DELEGATE_BATCH_MAX | No | Ceiling on tasks per `spawn_batch` call. | 10 |
| PI_DELEGATE_STATE_DIR | No | Where status-line state is published. | $XDG_STATE_HOME/pi-delegate-mcp |
| PI_DELEGATE_TRACE_ARGS | No | Max chars of tool arguments kept in the `status` toolCalls trace; the dropped length is recorded. | 400 |
| PI_DELEGATE_ALLOW_TOOLS | No | Comma list of extra tools to permit beyond the read-only default (`read, grep, find, ls`), e.g. `bash` or `web_search,fetch_content`. | |
| PI_DELEGATE_ALLOW_WRITE | No | Set to `1` to permit every tool (widens the read-only default). | |
| PI_DELEGATE_PROGRESS_MS | No | Progress notification interval during `run`, used to reset the host's request timeout. | 15000 |
| PI_DELEGATE_IGNORE_SCOPE | No | Set to `1` to ignore pi's `enabledModels` scope, allowing any configured model. | |
| PI_DELEGATE_STRICT_SCOPE | No | Set to `1` to honour `enabledModels` exactly, dropping the custom-provider bypass. | |
| PI_DELEGATE_TRACE_RESULT | No | Max chars of tool results kept in the `status` toolCalls trace; the dropped length is recorded. | 600 |
| PI_DELEGATE_STATUSLINE_LOG | No | File to append a timestamp to on every status line render, for debugging. | |
| PI_DELEGATE_STATUSLINE_WRAP | No | Status line command to wrap and append the pi segment to, e.g. `ccstatusline`. Omit to print the pi segment alone. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| initA | READ THIS FIRST. Reports what this server can reach and how to drive it: permitted tools, the default model, models available per provider, and the recipes for delegating. Every other tool refuses until this has been called once. |
| spawnA | Delegate a task to a pi agent running in the background. Returns a sessionId immediately, so nothing blocks. Poll with |
| spawn_batchA | Fan out several delegates in one call. Each task inherits the batch-level model, cwd, tools and extensions unless it overrides them. The whole batch is validated before any delegate starts, so a bad model name or a duplicate id fails everything instead of leaving half a fan-out running. Poll the result with |
| runA | Delegate a task to a pi agent and wait for the final answer. Blocks until done. Prefer |
| statusA | Check a background pi session. Returns state, turn count, tools used, latest text, and any pending questions the agent is waiting on. A non-empty |
| steerA | Redirect a running pi agent mid-task. The message lands after its current tool call finishes, before the next model call. Use this instead of aborting when the agent is going the wrong way. |
| answerA | Answer a question raised by a pi agent. Get |
| follow_upA | Send another prompt to a delegate that has already finished, keeping everything it read and said. Use this instead of spawning a fresh delegate and re-explaining the task: the session still holds its own context, which yours never had to absorb. Returns immediately; poll with |
| abortA | Stop a running pi session. Partial output stays readable via |
| sessionsA | List pi sessions held by this server, running and finished. Finished ones stay readable for review until evicted (keeps the newest 50). |
| forgetA | Drop a finished session from the review history, freeing its id for reuse. |
| modelsA | List models this delegate may use: pi's own scoped set plus any custom provider. Use to pick a |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 12 tools
Each tool targets a distinct state or action, and the three delegation entry points (spawn/run/spawn_batch) are explicitly differentiated by blocking behavior and fan-out. The message-sending trio (answer/steer/follow_up) is clearly disambiguated by delegate state, and descriptions even cross-reference each other (spawn vs steer vs follow_up).
Most names are concise lowercase verbs (spawn, run, steer, abort, forget, init) with a consistent compound pattern for spawn_batch/spawn variants. The deviation is noun-style list tools (sessions, models) and the short 'init', which break a strict verb convention but remain readable and predictable.
12 tools map cleanly onto the delegation lifecycle: launch (spawn/run/spawn_batch), monitor (status/sessions), interact (steer/follow_up/answer), stop (abort), and housekeeping (forget/models/init). Each earns its place with no redundant or filler tools.
The surface covers the full delegate lifecycle including batch fan-out, mid-task redirection, post-completion follow-up, Q&A unblocking, and cleanup. Minor gaps exist (e.g. no dedicated blocking wait-for-completion on a spawned session, no explicit per-provider model-filtering view), but agents can work around these via status/run.