Allows a supervising agent to assign investigation, analysis, implementation, and verification tasks to local Pi workers via MCP.
Also known as zguiyang/pi-task-exec, pi-task-exec, @zguiyang/pi-task-exec
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.4.0
- Last commit
- Oct 15, 2026
- License
- MIT
What is Pi TaskExec MCP?
Pi TaskExec allows a supervising agent to assign investigation, analysis, implementation, and verification tasks to local Pi workers via MCP.
Summary generated from the project's README
About Pi TaskExec MCP server
Delegating specific coding and research tasks to local workers is what Pi TaskExec enables for developers using supervising agents. By offloading investigation, analysis, implementation, and verification to local Pi workers, you can prevent execution details from cluttering your main agent's context. This setup is designed for users who manage multiple AI coding subscriptions or model resources and want to separate planning and review from actual execution.
The server operates by managing a full worker lifecycle through MCP, allowing you to spawn, steer, continue, or cancel tasks using commands like pi_abort and pi_release. It works with an installed and configured Pi executable and supports different capability profiles, including read-only inspect and read/write implement modes. You can configure the system for specific hosts like Codex, Zed, or OpenCode using a unified setup command.
Users can control worker behavior through optional model and thinking overrides for each worker. While the supervisor chooses the working directory, the MCP handles authorization without creating new worktrees or branches. This approach helps maintain a clean context for your primary agent while utilizing local compute for heavy lifting.
What you can do with it
- 1Offload heavy execution tasksAssign detailed implementation or verification tasks to a local worker to keep your main agent's context clean.
- 2Manage multiple AI subscriptionsDistribute work across different models or subscription plans by delegating tasks to specific Pi workers.
- 3Control worker lifecyclesDirectly manage active workers by spawning new ones, steering their progress, or canceling them when necessary.
- 4Configure multi-host environmentsSet up a unified delegation workflow across various coding environments like Zed or OpenCode.
Written from the project's README. Every use case is checked against a quote from it.
How to install Pi TaskExec MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Pi TaskExec MCP in Claude Code
$ claude mcp add pi-task-exec -- npx -y @zguiyang/pi-task-execInstall Pi TaskExec MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"pi-task-exec": {
"command": "npx",
"args": [
"-y",
"@zguiyang/pi-task-exec"
]
}
}
}Install Pi TaskExec MCP in VS Code
.vscode/mcp.json
{
"servers": {
"pi-task-exec": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@zguiyang/pi-task-exec"
]
}
}
}Install Pi TaskExec MCP in VS Code CLI
$ code --add-mcp '{"name":"pi-task-exec","type":"stdio","command":"npx","args":["-y","@zguiyang/pi-task-exec"]}'Install Pi TaskExec MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"pi-task-exec": {
"command": "npx",
"args": [
"-y",
"@zguiyang/pi-task-exec"
]
}
}
}Install Pi TaskExec MCP in Codex
$ codex mcp add pi-task-exec -- npx -y @zguiyang/pi-task-execInstall Pi TaskExec MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.pi-task-exec] command = "npx" args = ["-y", "@zguiyang/pi-task-exec"]
Install Pi TaskExec MCP in Gemini CLI
$ gemini mcp add -s user pi-task-exec npx -- -y @zguiyang/pi-task-execInstall Pi TaskExec MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"pi-task-exec": {
"command": "npx",
"args": [
"-y",
"@zguiyang/pi-task-exec"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablezguiyang/pi-task-exec is public and reachablegithub.com/zguiyang/pi-task-exec ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-15github.com/zguiyang/pi-task-exec ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @zguiyang/pi-task-execPass
- No critical advisory in the package or its dependencies24 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubPi TaskExec
Pi TaskExec lets a supervising agent assign bounded, independent investigation, analysis, implementation, and verification tasks to local Pi workers through MCP. The agent can also work directly when delegation would add more overhead than value.
The project grew out of the author's own workflow: using different models or subscription plans for planning and review versus execution. If you also have multiple AI coding subscriptions or model resources, you can try this division of work to make better use of them and keep execution details from crowding the main agent's context.
The author is still evaluating how this approach affects context usage, total token consumption, and actual costs; savings are not guaranteed. It addresses the author's own collaboration needs and may help others with similar workflows. You're welcome to try it and share your experiences, alternative views, or suggestions via Issues.
Highlights
- Runs tasks on local Pi using its locally configured default model, with optional per-worker
modelandthinkingoverrides. - Full worker lifecycle: spawn, status with bounded wait, steer, continue, cancel (
pi_abort), and release (pi_release), plus list. - Read-only
inspect(default) and read/writeimplementcapability profiles. - The Supervisor chooses the working directory; the MCP verifies authorization but never creates worktrees or branches.
- One unified MCP +
pi-delegateSkill setup with keyboard multi-select across Codex, Zed, and OpenCode.
Requirements
- Node.js >= 22.20
- An installed and configured
piexecutable
Quick start
From the project you want to configure, run the unified setup:
npx -y @zguiyang/pi-task-exec@latest setup
v0.3.1 is the current published release. This checkout prepares v0.4.0 with updated delegation guidance and multi-host CLI flows. The v0.3.0 worker-interface changes still apply; if you are upgrading from v0.2.2, follow the v0.3.0 migration notes.
On a TTY it opens a keyboard multi-select for the hosts (codex, zed,
opencode) plus a single scope (project or global), then runs and prints
a concise result; a routine run does not print the full plan and does not ask
for a Proceed? confirmation. Use --dry-run for the full plan (paths,
conflicts, warnings) and --json for stable machine-readable detail. The
pi-delegate Skill is installed from this repository (skills/pi-delegate)
at the matching release tag through the pinned Skills CLI skills@1.7.1.
Selections can also be given up front: --host may be repeated for several
hosts, and exactly one --scope applies to the whole run:
npx -y @zguiyang/pi-task-exec@latest setup --host codex --host zed --scope project
Restart each selected host afterward, grant project trust if asked, and
verify that pi_list is available inside the host.
Commands
npx -y @zguiyang/pi-task-exec@latest update
npx -y @zguiyang/pi-task-exec@latest uninstall
npx -y @zguiyang/pi-task-exec@latest doctor
npx -y @zguiyang/pi-task-exec@latest doctor --probe
setup, update, and uninstall share the same keyboard multi-select of
hosts and one scope, and also accept repeated --host flags. update
replaces the managed MCP entry and Skill files, so previously configured
custom settings must be supplied again.
uninstall removes only the managed pi-task-exec MCP entries for the
selected hosts and scope. The shared pi-delegate Skill is retained by
default; it is removed only when that removal is explicitly requested, which
prints a warning and reports the known hosts that still reference it first.
For a non-interactive run, add --remove-skill to request that removal.
The existing add and remove subcommands (add mcp, add skill,
remove mcp, remove skill) remain available as single-target commands.
doctor is read-only; --probe checks the package runtime only and never
creates a worker.
Learn more
- Full usage reference: docs/usage.md
- v0.4.0 release notes: docs/release-v0.4.0.md
- v0.3.1 release notes: docs/release-v0.3.1.md
- v0.2.2 → v0.3.0 migration: docs/usage.md
- Delegation policy: skills/pi-delegate/SKILL.md
- License: LICENSE
Pi TaskExec MCP questions
How do I add Pi TaskExec MCP to Claude Code?
Run claude mcp add pi-task-exec -- npx -y @zguiyang/pi-task-exec in your terminal. Add --scope user to make it available in every project.
How do I add Pi TaskExec MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What can Pi TaskExec do with local Pi workers?
It lets a supervising agent assign bounded, independent investigation, analysis, implementation, and verification tasks to local Pi workers.
Can I override the model used by the worker?
Yes, tasks run on local Pi using the default model, but you can provide optional per-worker model and thinking overrides.