English · 简体中文

pi-durabletask-mcp

Delegate work from Claude Code, Codex, or another MCP client to Pi Coding Agent, in its own context.

Quick start · Reference

Example workflow

You: Use Pi to review authentication for missing permission checks. Don't edit files.
     Explicitly set durable: true so we can continue in another window.
  → spawn with the absolute repo cwd and durable: true
While running: Focus on tenant isolation; skip style issues.
  → steer
After the review: Suggest a regression test for the most serious finding.
  → follow_up in the same session
Switching windows: Save findings and next steps → handoff save
New window: Read this repo's handoff → handoff read; follow resumeHint

To collect results, the main agent loops wait with until: "settled". If Pi asks a question, use answer with the question ID, then wait again.

Related MCP server: codex-router

What you can do

• Separate context: Pi reads and searches; your main agent collects findings.

• Attachments: pass a diff or notes by file path with attachments, instead of pasting them into the prompt.

• Multiple models: spawn_batch starts tasks with individually selected models.

• Live steering: steer redirects work after the current tool call.

• Follow-ups: follow_up keeps context in the same long-lived session; turns accumulate.

• Final-turn wrap-up: tools are disabled on the last turn and the model is asked to provide a final answer; results include token usage and cost.

• Recovery: explicit durable: true saves checkpoints to SQLite.

• Handoff: leave a note for the next Claude/Codex window.

• Native MCP: nativeMcp explicitly selects servers and tool permissions; third-party extensions are enabled separately.

Quick start

Requires Node.js 22.19+ and global Pi. CI-tested with Pi 1.0.0 and 1.0.2. Model calls use your own provider credentials and quota.

1 · Install

Already configured Pi? Install the bridge:

npm install -g pi-durabletask-mcp

The bridge links to the global Pi SDK, so install Pi before the bridge:

npm install -g @earendil-works/pi-coding-agent@1.0.0
pi  # configure a provider or use /login

Search uses Pi's downloaded rg or ripgrep on PATH. Authentication →

Global Pi is still required.

git clone https://github.com/Nyarlathoteppppp/pi-durabletask-mcp.git
cd pi-durabletask-mcp
npm ci
npm run build

Connect with node /absolute/path/pi-durabletask-mcp/dist/index.js instead of the installed command.

2 · Connect

claude mcp add --scope user pi -- pi-durabletask-mcp

Add to ~/.codex/config.toml:

[mcp_servers.pi]
command = "pi-durabletask-mcp"

Already connected? Update the existing entry and reconnect. Other clients →

3 · Try a review

Use Pi to review authentication for missing permission checks. Don't edit files. Report file locations and suggested regression tests.

The agent uses spawn → wait(until: "settled"), answering questions with answer. Try the steering and follow-up prompts above. init is optional diagnostics; models lists available models.

Connect the MCP server first; this skill only guides tool use. Choose your client's user-level directory and download just SKILL.md:

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

Start a new client session after installing.

Defaults & recovery

Tasks use your configured model, read-only tools and memory storage by default; memory sessions disappear when their MCP process exits. With explicit durable: true, recovery happens after a bridge restart: per-run time limits include downtime, and tools with unknown outcomes are not blindly replayed—verify external state before retrying. handoff stores notes written by the main agent; reading them does not take over execution. Cross-window continuation requires a durable task with its original history and note still retained; a live owner must release the task before another process can continue it.

Documentation

• Agent instructions · Tools · Configuration

• Handoff · Native MCP

• Recovery, ownership & retention

• Development · Changelog · Issues

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