Pi Durateam

English · 简体中文

pi-durateam

A team of Pi agents for Claude Code and Codex, on any provider, with runs built to finish.

Quick start · Team · MCP tools · Dura · Reference

Renamed from pi-durabletask-mcp: install pi-durateam. The old command still works; configuration, PI_DELEGATE_* variables, stored state and tool names are unchanged.

Your main agent plans, picks the models and judges the results. The reading, searching and cross-checking run on Pi delegates — Gemini, Grok, GPT, DeepSeek or any other provider Pi supports — and spend those quotas instead of your Claude Code or Codex one; what comes back is a compact status and the final report, or just a file path. In our own pre-release review, four agents read about two million tokens of this codebase on Gemini, Grok and a GPT model, and our Claude session received about 7 KB of reports.

• team — one task or several in parallel, the same question to several models, forks that read once and answer many questions, an opt-in coordinator, and MCP servers (read-only GitHub, a browser) granted per delegate.
• dura — every run has turn, time and tool-call budgets and a last turn without tools, reserved for the answer. Opt in to a soft deadline, model fallback on provider errors, and sessions that survive a server restart.

For example, ask your agent: "Use Pi to review the attached diff with Gemini, Grok and GPT in parallel. Don't edit files. Report only real defects with file:line." It calls spawn_batch with one shared prompt and three models, collects with wait, and gets three independent reports with token usage and cost.

Quick start

Requires macOS or Linux, Node.js 22.19+ and Pi. CI runs Node.js 22 and 24 against Pi 1.0.0, 1.0.4, 1.1.0 and 1.3.0. Model calls use your own provider credentials.

1 · Install Pi (skip if you have it) and log in to a provider:

curl -fsSL https://pi.dev/install.sh | sh
pi  # then /login, or configure a provider

2 · Install pi-durateam:

npm install -g pi-durateam@latest

Or install from source

git clone https://github.com/Nyarlathoteppppp/pi-durateam.git
cd pi-durateam && npm ci && npm run build
# below, use `node /absolute/path/pi-durateam/dist/index.js` instead of `pi-durateam`

3 · Connect. Claude Code:

claude mcp add --scope user pi -- pi-durateam

Codex (~/.codex/config.toml):

[mcp_servers.pi]
command = "pi-durateam"

The Codex desktop app starts MCP servers with a minimal PATH (no Homebrew or nvm directories), so it may find neither pi-durateam nor the node it runs on. The server then never starts and the session simply has no Pi tools. Use absolute paths there:

[mcp_servers.pi]
command = "/opt/homebrew/bin/node" # output of `which node`
args = ["/opt/homebrew/lib/node_modules/pi-durateam/dist/index.js"] # under `npm root -g`
[mcp_servers.pi.env]
PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin" # inherited by what the server starts

Reconnect the MCP server after updating pi-durateam or Pi. Other clients →

4 · Try it: "Use Pi to check the auth module for missing permission checks. Read only." init shows models, provider credentials and settings; models lists what delegates may use.

Optional: install the Agent Skill

The skill teaches your agent the workflow. Put SKILL.md in your client's skills directory:

dir="$HOME/.claude/skills/pi-durateam" # Claude Code
# dir="$HOME/.agents/skills/pi-durateam" # Codex: use instead
mkdir -p "$dir"
curl -fsSL https://raw.githubusercontent.com/Nyarlathoteppppp/pi-durateam/main/skills/pi-durateam/SKILL.md \
  -o "$dir/SKILL.md"

Team: several models on one job

• Delegate. spawn starts one task in the background and returns a sessionId at once. spawn_batch starts up to 4 per call by default (PI_DELEGATE_BATCH_MAX) and checks every task first, so nothing starts if one is bad. run blocks, for quick questions. Collect with wait and until: "settled".
• One question, several models. A batch-level prompt goes to every task; each task names its model, and its own prompt is appended. Different model families miss different things, but agreement is not proof: verify findings before acting.
• Read once, ask many. forkFrom starts new tasks from a finished session's transcript, including the files it already read; each fork gets fresh budgets.
• Steer and continue. steer a running delegate, answer its questions, follow_up a finished one (it keeps what it read), abort when needed. status reports idleMs and phase, which tell slow reasoning from a hung request.
• Material in, reports out. attachments passes a diff or notes by absolute path; saveTo / saveDir write long reports to files and return the path; usage gives tokens and cost.
• Coordinator (opt-in). Pass a coordinator plan to spawn: a Pi coordinator dispatches your members, can ask one a targeted follow-up, and writes one synthesis that cites the original reports. Requires codemode in PI_DELEGATE_ALLOW_TOOLS. For most work spawn_batch and your own judgment are simpler. Workflow →

MCP tools per delegate

A delegate can use MCP servers from Pi's mcp.json — read-only GitHub, Serena, a browser, web search — selected per task; nothing is on by default. Add the server to ~/.pi/agent/mcp.json, permit its exact tool names in pi-durateam's environment (PI_DELEGATE_ALLOW_TOOLS="mcp__github__get_file_contents,mcp__github__search_code") and reconnect. Then select them per call:

{
  "cwd": "/absolute/repo",
  "nativeMcp": true,
  "mcpServers": ["github"],
  "tools": ["mcp__github__get_file_contents"],
  "prompt": "Read package.json of OWNER/REPO with GitHub MCP and report its version."
}

• Only the servers in mcpServers are connected. Of their tools, the delegate gets only the mcp__<server>__<tool> names listed in tools and permitted by PI_DELEGATE_ALLOW_TOOLS; selecting a server never grants all of its tools.
• A call that selects servers but grants none of their tools is refused before anything starts — for example with tools omitted (the read-only default), or with only codemode or tool_search, which reach only tools named in tools. tools: [] remains a tool-free run.
• Name tools the way the server's exposure in mcp.json reaches them: with direct the mcp__<server>__<tool> name is enough (the example above), with codemode add codemode, with deferred add tool_search.
• extensions can stay false. Batch tasks inherit nativeMcp and mcpServers; coordinator members select their own, and their servers need direct exposure.
• A permitted MCP tool may write or act outside cwd, and the secret-path guard does not cover external servers. Grant capabilities deliberately.

Setup for GitHub, Serena and agent-browser: optional tools. Web search: research. Exposure modes and recovery: native MCP.

Dura: runs built to finish

Always on

• Turn, time and tool-call budgets. spawn and spawn_batch default to 30 turns and 10 minutes, run to 12 turns and 5 minutes; the ceilings are PI_DELEGATE_MAX_TURNS (default 50) and PI_DELEGATE_MAX_DURATION_MS (default 15 minutes). maxToolCalls caps the delegate's own calls.
• At 75% of the turn or tool-call budget, or after 2/3 of the time, the delegate is told to wrap up; its last turn has no tools and is reserved for the answer.
• answerState flags an empty (missing) or cut-off (partial) answer. A run that ends without an answer (aborted, error) returns its latest substantial text as salvagedText. Finished results name the model that answered.

Opt-in

• Soft deadline (PI_DELEGATE_DEADLINE_GRACE_MS): at the deadline the tools go, no new tool call starts, and the delegate has this long to answer; only a run still without an answer is aborted.
• Model fallback (PI_DELEGATE_FALLBACK_MODELS, or fallbackModels per call): after a provider error that outlasts Pi's retries, the run continues in the same session on the next model listed, e.g. "xai/*:high,antigravity/gemini-*". In our use, a Codex quota error now continues on Grok within seconds.
• For models that keep calling tools: PI_DELEGATE_ANSWER_GRACE=1 gives one more tool-free turn, PI_DELEGATE_TOOL_CHOICE_NONE sends toolChoice: "none" on that turn, PI_DELEGATE_FINISH_THINKING lowers the thinking level once a run is wrapping up.
• Durable sessions (durable: true): SQLite checkpoints; after a server restart the session resumes with its id, history and budgets, and a tool call whose outcome is unknown is never blindly replayed. Finished ones are kept for 7 days by default (retentionDays, PI_DELEGATE_RETENTION_DAYS).
• handoff: save a note in one Claude/Codex window, read it in another to continue the same durable session.

Safe defaults

• A call that omits tools gets the read-only set (read, grep, find, ls, or your PI_DELEGATE_DEFAULT_TOOLS); anything more must be permitted with PI_DELEGATE_ALLOW_TOOLS. This is not a sandbox: a delegate given bash can do anything you can.
• Secret paths (.env, ~/.ssh, credentials) are refused for attachments, reads and searches; PI_DELEGATE_SECRET_GUARD=0 turns this off.
• Sessions live in memory and end with the MCP process. Durable storage, fallback, the soft deadline, the answer grace turn, native MCP and the coordinator are off unless you turn them on.
• By default at most 4 delegates run at once per server process (PI_DELEGATE_MAX_CONCURRENT). A model name that does not resolve is refused, never replaced by the default.

Documentation

• Reference: tools, configuration, authentication, native MCP
• Optional MCP tools · Web research · Review and synthesize · Coordinator
• Development · Changelog · Issues

MIT · Built on howznguyen/pi-delegate-mcp and Pi Durable.