pi-subagent
This server lets you delegate coding/repo tasks to Pi through MCP and track their runs.
pi_delegate: start a Pi subagent task with a prompt, session name, optional working directory, goal, mode (syncorasync), timeout, and constraints (model, thinking level, allowed/excluded tools).pi_status: poll or long-wait for a run result byrunId, optionally reopening the read-only transcript window.Supports named sessions for continuing conversations and up to four concurrent runs.
Provides async execution with returned
runIds and terminal states: completed, error, killed, timeout.Enables transcript capture and Windows viewer control via environment variables.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pi-subagent Refactor the login component and update tests."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Pi-Team
Delegate tasks to the Pi CLI through MCP, with named sessions, sync/async execution and a read-only transcript window on Windows.
Based on guyiicn/pi-subagent.
If you are using Mattpocock's Skills, try Matts-Skills-with-Pi-Team.
Install
Requires Node.js, npm and Pi configured with access to a model provider.
npm install -g @earendil-works/pi-coding-agent
git clone https://github.com/TouHousand-Years/Pi-Team.git
cd Pi-Team
npm ci
npm run buildEnsure pi is on the MCP server's PATH. Run npm run build again after updating the checkout.
Related MCP server: win-cli-mcp-tmyy
Configure
Add this to your MCP host configuration, using the absolute path to dist/server.js:
{
"mcpServers": {
"pi-subagent": {
"command": "node",
"args": ["/absolute/path/to/Pi-Team/dist/server.js"]
}
}
}On Windows, use a path such as C:/Projects/Pi-Team/dist/server.js. The MCP server keeps the name pi-subagent for compatibility.
Adapted skills
This repository includes five skills under skills/ that turn the two MCP tools into reusable, checkable workflows. The skills define how the host scopes work, delegates it to Pi, verifies the result and stops safely.
Skill | Use it for | Main boundary |
The shared delegation contract used by the other Pi skills: model selection, prompt composition, file ownership, result collection, concurrency and failure handling. | It supplies transport rules only; the active specialized skill still defines the task, outputs and acceptance criteria. | |
Evidence-backed repository investigation, including architecture, tests, recent commits, caches, frontends, concurrency, networking and reproducible failures. | It keeps product files read-only and returns conclusions with paths, line references, commands and explicit evidence gaps. | |
Bounded implementation or repository work with a closed baseline-execute-verify-correct loop. It fits coding, bulk edits, experiments, log analysis and tasks with observable checks. | Pi owns the declared output files; the host reviews them read-only and sends corrections back through another bounded delegation. | |
Long or consequential translations that require complete coverage, stable terminology and preservation of headings, tables, citations, code and formulas. | It translates from explicit source files, uses a glossary when needed and marks unresolved wording instead of silently guessing or omitting content. | |
High-leverage implementation plans, trade-off decisions and recovery plans after exploration or experiments have produced a compact evidence brief. | The planner receives text only: it has no tools, network access or write permission, and it never performs the implementation. |
The usual composition is pi-explorer for facts, pi-ultra-planner for a difficult decision, and pi-worker for execution. pi-translator is a separate document workflow. All four specialized skills delegate through pi-team, which uses only pi_delegate and pi_status.
Delegate a task
Call pi_delegate:
{
"prompt": "Review the parser and write findings to review.md.",
"session": "review-parser",
"cwd": "C:/Projects/example",
"goal": "Review parser correctness",
"mode": "sync",
"runTimeoutMs": 240000
}promptandsessionare required. New sessions also requiregoaland an existingcwddirectory.Reuse
sessionto continue a conversation after its current Run finishes. You may omitcwdandgoal; an explicitcwdmust match the original.mode: "sync"waits for completion.mode: "async"(default) returns arunIdto collect later.runTimeoutMsdefaults to600000(10 minutes). Keep synchronous calls within your host's tool-call timeout.Up to four Runs can execute at once, with one per session. Runs stop after 5 minutes without recorded tool-result progress.
Optional constraints configure each call independently:
{
"model": "<model identifier configured in Pi>",
"thinking": "high",
"tools": ["read", "bash", "edit", "write"]
}Place this object under constraints in pi_delegate. excludeTools is also supported. Thinking levels are off, minimal, low, medium, high and xhigh. For tool names beyond those shown, set allowUnknownTools: true. Resend constraints when continuing a session if needed.
Collect results
Call pi_status with the returned runId:
{
"runId": "<runId>",
"waitTimeoutMs": 25000
}The call waits until completion or the wait timeout (default: 25 seconds). waitTimeoutMs: 0 returns immediately. If status is still running, wait again using the same runId. Terminal states are completed, error, killed and timeout; inspect result or error as appropriate.
A host timeout does not necessarily stop the Run. If you have its runId, collect that Run before starting another. Old Run IDs are unavailable after a server restart, though session metadata and transcripts remain on disk.
Windows viewer
Each Run automatically opens a read-only transcript window on Windows. Closing it does not stop the Run. To reopen it, call pi_status with "openWindow": true.
Set PI_SUBAGENT_VIEWER=off to disable windows. Delegation and transcript capture work without the viewer.
Environment variables
Variable | Purpose / default |
| Pi executable override. |
|
|
| Viewer executable; |
| Override |
| Session metadata; |
| Full transcripts; |
Transcripts include prompts and tool output. Inactive completed bundles are cleaned after 7 days, with oldest-first cleanup targeting a 2 GiB quota.
Available Tools
2 toolspi_delegateC
委派任务给 Pi 子代理(默认 async)
Inputs: prompt (required), session (required), cwd, goal, +4 more.
pi_statusC
取 run 结果(long-poll);openWindow 可重开该 Run 的只读窗口
Inputs: runId (required), openWindow, waitTimeoutMs.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: pi_delegate initiates a task delegation, while pi_status retrieves the result of a run. There is no overlap or ambiguity between them.
Both tools follow a consistent pi_ prefix and use a verb_noun pattern (delegate, status). The naming is predictable, though the set is too small to fully demonstrate a broader convention.
Two tools is on the thin side for a subagent delegation server, but it may be sufficient for a minimal async task lifecycle. The count is borderline but not unreasonable.
The pair covers the basic delegate-and-poll lifecycle, but there is no explicit cancel, list, or error-handling tool. Agents can work around this by waiting for status, but the surface feels minimal.
Related MCP Connectors
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Start and manage Reason cloud coding agents, projects and sessions from any MCP client.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Remote MCP server for Tandem docs, install guides, SDKs, workflows, and agent setup help.
Related MCP Servers
- AlicenseCqualityCmaintenanceEnables MCP hosts to delegate coding tasks to Pi CLI as a programmable sub-agent with session tracking and process management.73MIT
- AlicenseBqualityDmaintenanceEnables AI clients to execute Windows commands, manage files, query system information, and perform code checks via MCP protocol.241Business Source 1.1
- AlicenseAqualityCmaintenanceA Windows-native MCP gateway that lets any MCP-capable host orchestrate local coding-agent CLIs as external workers.11Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables Claude Code to delegate coding implementation and testing to a local pi agent via MCP tools, including dispatching task books, monitoring status, steering or aborting runs mid-execution, and retrieving results and transcripts.4MIT