pi-subagent-mcp

MCP server that exposes pi (pi --mode rpc) as a sub-agent for MCP-capable coding assistants (e.g. Kimi CLI).

Build

npm install
npm run build

Related MCP server: pi-sylvan

Tools

Extension UI dialogs (bidirectional interaction)

pi extensions can block on select/confirm/input/editor dialogs (extension_ui_request). By default (interactive: true) the server surfaces these as pendingRequest in pi_status/pi_wait — which returns early — and the caller answers with pi_respond. With interactive: false (unattended runs) dialogs are auto-cancelled, preserving the original behavior.

Note: project-local pi extensions (.pi/extensions/) only load when the project is trusted — pass approve: true to pi_dispatch to grant that for the run. Also, pi delays the command response for extension commands that block on a dialog; the server therefore treats dialog activity as command acceptance so pi_dispatch/pi_send return instead of deadlocking.

Attaching to terminal pi sessions (bridge)

pi's RPC mode is stdio-only, so a pi already running in your terminal cannot be attached retroactively. The bridge extension solves this: installed once, every pi session started afterwards (interactive TUI included) exposes a Unix socket at ~/.pi/bridge/<sessionId>.sock that this server can attach to.

Install (user scope, loads in every pi session):

pi install /absolute/path/to/extensions/bridge.ts

Then from any MCP client:

pi_bridges                    → discover running sessions
pi_attach { sessionId }       → get a taskId; pi_send / pi_wait / pi_read /
                                pi_status / pi_abort work as usual
pi_notify { taskId, message } → text appears on that pi's TUI console
pi_detach { taskId }          → disconnect; the terminal session stays alive

Limitations: sessions started before the install can never be attached; attached sessions answer their own extension dialogs in their terminal (no pendingRequest); session replacement (/new, /resume) ends the attachment (re-attach via pi_bridges); Unix sockets only (no Windows named pipes). See docs/design/terminal-bridge.md.

Configuration

Environment variables:

• PI_SUBAGENT_SESSION_DIR — where pi session files are stored (default: .pi-subagent/sessions/ next to the package).

• PI_SUBAGENT_PI_PATH — override the pi binary path (default: pi).

MCP registration (example): point your client at node /path/to/dist/src/server.js.

Test

npm test   # unit + smoke + (if pi is installed and logged in) integration

Additional end-to-end scripts in scripts/ (acceptance-test.mjs, mcp-e2e-test.mjs, dialog-e2e-test.mjs, bridge-e2e-test.mjs). Issues found during development are logged in docs/issues/; design notes in docs/design/.