Pi TaskExec

What Pi TaskExec MCP server does

Pi TaskExec MCP server connects an MCP host to locally installed Pi coding-agent processes. It is designed for a split workflow: a primary agent handles planning, decisions, and review, while Pi workers carry out bounded implementation tasks. This can help keep execution details out of the primary context when the work is easier to delegate.

Workers use Pi's locally configured default model unless a worker receives an optional model override. A thinking-level override is also available. The project does not promise lower token use or cost; those outcomes depend on the host's workflow, models, subscriptions, and task mix.

The runtime is host-agnostic in its worker supervision model. The documented setup supports a unified MCP and pi-delegate Skill arrangement for Codex, Zed, and OpenCode.

How it works

The supervisor supplies the working directory for a task. Pi TaskExec verifies that the requested directory is authorized, but it does not create Git worktrees or branches. This makes the host responsible for choosing the project location and managing any repository structure around the worker.

The worker lifecycle covers creation, status checks with bounded waiting, steering an active worker, continuing work, cancellation through pi_abort, release through pi_release, and listing workers. The current release uses seven worker tools, requires cwd and thinking, and supports activity cycles. A pi_list call can be used after setup to confirm that the host can access the MCP.

Two capability profiles separate access levels. The default inspect profile is read-only. The implement profile permits read and write operations, making it the appropriate choice for tasks that must modify project files.

Setup and configuration

The runtime requires Node.js 22.20 or newer and an installed, configured pi executable. From the project being configured, run:

npx -y @zguiyang/pi-task-exec@latest setup

Setup asks for the host and scope, displays the MCP and Skill files it plans to write, and requests confirmation. Host and scope can be supplied in advance, for example with --host codex --scope project, but confirmation still occurs. The pi-delegate Skill is installed from the repository at the matching release tag through the pinned Skills CLI.

Restart the host after setup and grant project trust if the host requests it. Then verify that pi_list is available. The update command replaces managed MCP and Skill files, so custom settings need to be provided again. doctor performs read-only checks, while doctor --probe checks the package runtime without creating a worker.

Limitations and notes

Pi TaskExec MCP server requires a usable local Pi installation; it is not described as a remote worker service. Authorization is checked, but repository worktrees and branches remain outside its responsibilities. Its value also depends on having a suitable delegation workflow and, where relevant, separate model or subscription resources.

The project is currently documented around release 0.3.0. That release changes the worker interface from the earlier version, including required cwd and thinking fields, activity cycles, and separate abort and release operations. Users upgrading from 0.2.2 should consult the migration notes before replacing an existing setup.

The documentation names Codex, Zed, and OpenCode as hosts for the unified MCP and Skill setup. It does not establish support for every MCP client or guarantee savings in context, tokens, or cost.