# Pi TaskExec MCP server

> Allows a supervising agent to assign investigation, analysis, implementation, and verification tasks to local Pi workers via MCP.

- Repository: https://github.com/zguiyang/pi-task-exec
- Page: https://hostedmcp.org/servers/zguiyang/pi-task-exec
- Transport: stdio
- Stars: 0
- License: MIT
- Latest version: 0.4.0

## Install

### Claude Code

```sh
claude mcp add pi-task-exec -- npx -y @zguiyang/pi-task-exec
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "pi-task-exec": {
      "command": "npx",
      "args": [
        "-y",
        "@zguiyang/pi-task-exec"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "pi-task-exec": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@zguiyang/pi-task-exec"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"pi-task-exec","type":"stdio","command":"npx","args":["-y","@zguiyang/pi-task-exec"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "pi-task-exec": {
      "command": "npx",
      "args": [
        "-y",
        "@zguiyang/pi-task-exec"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add pi-task-exec -- npx -y @zguiyang/pi-task-exec
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.pi-task-exec]
command = "npx"
args = ["-y", "@zguiyang/pi-task-exec"]
```

### Gemini CLI

```sh
gemini mcp add -s user pi-task-exec npx -- -y @zguiyang/pi-task-exec
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "pi-task-exec": {
      "command": "npx",
      "args": [
        "-y",
        "@zguiyang/pi-task-exec"
      ]
    }
  }
}
```

## Tools (7)

- `pi_spawn`: Start one bounded independent investigation, analysis, implementation, or verification task when delegation offers a useful benefit. Give a clear goal, context, scope, expected result, and stopping condition. Simple or context-dependent work can be done directly. Use inspect for read-only work; implement permits writes and shell commands only within authorized scope. The supervisor retains global decisions and final review. A failed implement worker may leave partial edits. Success means accepted, not completed.
- `pi_status`: Check a worker's progress, state, and the authoritative result of its current activity cycle. The result comes only from Pi's final assistant message and is independent of streamed diagnostics. Settled means the cycle ended; it does not mean the result is correct. Use waitMs to block, event driven, until the cycle settles or fails; a wait timeout does not cancel the worker. Avoid frequent busy polling.
- `pi_steer`: Correct the direction of a running worker when its current task is drifting. Use only while it is running; this is not a follow-up. For a related next task after settlement, use pi_continue.
- `pi_continue`: Give the same worker a related follow-up that benefits from its current context. While running, the follow-up is queued and delivered inside the current activity cycle; once the cycle has settled (or failed), it starts a new cycle on the same process. Accepted/queued is not completed. Use a new worker for unrelated work. Cannot reuse a released or crashed worker.
- `pi_abort`: Cancel the current activity cycle of a running worker without releasing its process or live-worker slot. The worker can be continued afterwards when its process is still alive. A worker with no running cycle returns its existing snapshot unchanged. Use pi_release to terminate the process and free the slot.
- `pi_release`: Release a worker's process and live-worker slot without reverting its edits or deleting files. Releasing a settled or failed worker preserves its authoritative result and failure. Releasing a running worker cancels and terminates it. Release is idempotent; if termination cannot be confirmed the snapshot carries releaseError and pi_release can be retried.
- `pi_list`: Inspect the current worker fleet before spawning more workers. Results are newest first and include live workers (running, settled, or cycle-failed), which still occupy slots and can be continued or released, plus bounded released/crashed snapshots, which cannot be reused. The list does not include the configured worker limit.

## FAQ

### 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.
