Supports spawning Pi coding-agent workers in isolated Git worktrees, keeping worker edits separate from the caller's checkout. Worker tools do not merge branches or delete worktrees, so changes must be reviewed before integration.
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-worker-mcp spawn a worktree worker to fix the failing auth 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.
A host-agnostic MCP worker runtime for supervising local Pi coding-agent processes. It uses local stdio MCP and Pi RPC; it is not a hosted service and does not manage Pi credentials, providers, or default models.
Prerequisites: Node.js 20+, a locally installed and configured pi executable, and Git when using isolated worktrees.
npx -y @zguiyang/pi-worker-mcp@latest setupThe setup command selects supported hosts and pins their launch configuration to the exact CLI version. A host never silently drifts to a new release.
Related MCP server: pi-durabletask-mcp
Host | Global | Project | Configuration |
Codex |
|
| TOML |
Zed |
|
| JSON |
OpenCode |
|
| JSON |
Project scope is relative to the directory where setup runs. Zed starts project-defined MCP servers only after the worktree is trusted. Existing configuration is minimally merged; uninstall removes only this server’s entry.
npx -y @zguiyang/pi-worker-mcp@0.1.1 setup --host codex --scope project
npx -y @zguiyang/pi-worker-mcp@0.1.1 setup --host opencode --scope globalAny stdio MCP client can launch:
command: npx
args: -y @zguiyang/pi-worker-mcp@0.1.1 serveThis is the release configuration. Do not point user installations at a checkout’s dist/ directory.
pi-worker-mcp serve
pi-worker-mcp setup [--host codex|zed|opencode] [--scope project|global]
pi-worker-mcp doctor [--host …] [--scope …]
pi-worker-mcp update [--host …] [--scope …]
pi-worker-mcp uninstall [--host …] [--scope …]
pi-worker-mcp versiondoctor checks Node, the local Pi executable, and selected host configuration without starting a model task or exposing credentials. update is not a package manager: run a newer CLI via npm/npx and it updates only selected configuration pins. uninstall never removes a whole host config, Pi config, Skills, or npm cache.
Pi owns provider authentication, available models, and its default model. The worker runtime can validate an optional per-worker override and report the effective model, but never configures credentials. Core runtime behavior—Pi RPC, lifecycle, model semantics, concurrency, and permissions—is independent of Codex, Zed, and OpenCode. Host adapters only read, merge, and remove launch configuration.
pi_spawn, pi_status, pi_steer, pi_continue, pi_abort, and pi_list supervise bounded local workers. Successful spawn/continuation means Pi accepted work, not that it is correct; the supervising agent must inspect results and integrate changes. Use worktree mode for isolated implementation work.
Environment variable | Default | Purpose |
|
| Pi executable |
|
| Maximum live workers |
|
| Per-RPC timeout |
|
| Idle deadline; |
|
| Activity-cycle deadline |
| current directory | Path-delimited allowed roots |
No secret environment variable is required; Pi reads its own local authentication configuration.
Source mode is only for contributors:
npm install
npm run build
node dist/index.js serveFor release-equivalent testing, use npm pack and execute the resulting .tgz from a clean temporary directory. npm link is not package acceptance.
server.json follows the official MCP Registry schema and declares an npm stdio package representation. npm and Registry publication remain separate, explicit actions.
This server cannot be deployed
Task tracking built for coding agents. Work is leased, so two agents never take the same SubTask.
Hand tasks, bugs and finished work to AI coding agents, and get back a write-up with evidence.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
