Pi

Pi

The Pi coding agent is a first-party Chorus integration, distributed as the published npm package @chorus-aidlc/chorus-pi. It ships Chorus workflow skills, read-only reviewer sub-agents, the official pi subagent tool, and session-aware extension hooks through Pi’s native extension + skill + agent mechanisms — installed with a single pi install.

Pi can also run as a wakeable --agent pi daemon backend: the Chorus daemon wakes a headless pi session on remote dispatch, so Pi participates in the reversed-conversation loop like Claude Code, Codex, and Kiro.

Before installation, create an agent key by following Prepare agent access.

Prerequisites

• The pi CLI installed (see pi.dev).
• The pi-mcp-adapter package — the one runtime dependency that exposes the Chorus chorus_* MCP tools to Pi (Pi has no native MCP):

  pi install npm:pi-mcp-adapter

  There is no separate sub-agents package to install — chorus-pi bundles pi’s official subagent tool itself.
• A Chorus API key (starts with cho_).

Step 1: Export environment variables

export CHORUS_URL="http://localhost:8637"
export CHORUS_API_KEY="cho_REDACTED"

Add these to ~/.bashrc / ~/.zshrc so Pi reads them on startup. CHORUS_URL may be the root URL or the full /api/mcp endpoint. If these are unset, the extension falls back to reading the chorus server entry from .mcp.json.

Step 2: Configure the MCP server

Pi’s pi-mcp-adapter auto-discovers standard MCP config files. Place a .mcp.json at the project root (or ~/.pi/agent/mcp.json globally) so the main agent gets the chorus_* tools:

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "http://localhost:8637/api/mcp",
      "headers": { "Authorization": "Bearer cho_REDACTED" }
    }
  }
}

Literal URL + literal Bearer work out of the box — Pi does not require ${VAR} expansion in .mcp.json. Keep .mcp.json out of version control because it contains the agent key.

Step 3: Install the chorus-pi package

pi install npm:@chorus-aidlc/chorus-pi

That is the whole install. The subagent tool ships inside the package, and the three reviewer agents are discovered directly from the package’s own agents/ directory — there is no separate sub-agents dependency and no manual copy of agent files into ~/.pi/agent/agents/. Restart Pi (/reload or a fresh session) so the extension, skills, and reviewer agents load.

Developing chorus-pi locally? Install from a repo checkout instead: pi install ./packages/chorus-pi.

Verify the connection

Restart Pi, inspect /mcp, and ask Pi to call chorus_checkin. Confirm the response shows the expected agent identity and permissions, and that the first turn reports a # Chorus Plugin — Active context with your checkin info. Type /skill:chorus to confirm skills loaded, and inspect /subagents for chorus-proposal-reviewer.

Capabilities

• 13 skills driving every AI-DLC stage — /skill:chorus, /skill:idea, /skill:proposal, /skill:develop, /skill:review, /skill:quick-dev, /skill:yolo, /skill:brainstorm, /skill:orchestrate, /skill:docs, /skill:chorus-cli, plus the openspec-aware and spec-lite sub-procedures.
• 3 read-only reviewer sub-agents — chorus-proposal-reviewer, chorus-task-reviewer, chorus-code-reviewer — discovered package-relative (no copy) and spawned via the blocking subagent tool; they post a VERDICT comment and stop.
• The official pi subagent tool, bundled at extensions/subagent/ (pi’s reference pattern) — no third-party sub-agents package required. It also coexists with the community pi-subagents package (nicobailon): both register a subagent tool, so exclude the bundled one via a settings.packages filter, and chorus-pi’s session lifecycle handles that package’s async / detached subagent runs alongside the bundled blocking runs. See the chorus-pi README for the filter and setup.
• Session-aware extension subscribing to Pi’s native events (session_start → chorus_checkin
  • spec-mode resolution, tool_call on subagent → per-worker Chorus session, tool_result → close the worker session + reviewer nudges, session_shutdown → cleanup).

The extension is config-by-env (Pi has no plugin-settings UI). CHORUS_SPEC_MODE selects openspec, lite, or off; without it, usable OpenSpec wins, otherwise the session uses spec-lite. The older CHORUS_OPENSPEC_MODE=off disables only OpenSpec, so the fallback is lite, not free-form. Use CHORUS_SPEC_MODE=off for no local spec files. See OpenSpec mode and Spec-lite mode. Reviewer toggles remain CHORUS_ENABLE_{PROPOSAL,TASK,CODE}_REVIEWER (default true).

Run pi as a wakeable daemon backend

Pi is a first-class wakeable daemon backend — the Chorus daemon wakes a headless pi session on remote dispatch (an idea/task assigned to your agent, an @mention, a proposal decision).

The simplest path is chorus agents add: select Pi in the agent checklist and it installs pi-mcp-adapter and chorus-pi through pi install, seeds pi as a wakeable agent in ~/.chorus/daemon.json, and — if you opt in — installs the boot daemon that wakes it. To wire it by hand, run the daemon with the pi backend:

chorus daemon --agent pi

• The daemon resolves the pi executable from PATH (override with CHORUS_PI_PATH) and runs it headless (pi --mode json -p), exporting CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE into the woken session.
• Pi has no permission system, so no sandbox / skip-permissions flag is involved — the chorus and yolo daemon modes run pi identically.
• A woken pi reaches Chorus MCP tools only through this package’s extension / pi-mcp-adapter, so keep chorus-pi installed in the environment the daemon wakes (the npm install makes that reliable).

The daemon supplies the Chorus connection (CHORUS_URL, CHORUS_API_KEY, and CHORUS_AGENT_PROFILE), but does not obtain model-provider credentials for you. Supply those through the agent’s env in ~/.chorus/daemon.json, the daemon’s inherited environment, or the provider’s supported credential store. A systemd --user service does not inherit exports from your login shell. The daemon guide covers model and thinking args, per-agent env, service credentials, and the required restart.

Common issues

• MCP server is missing: place .mcp.json in the project root (or ~/.pi/agent/mcp.json), or run /mcp setup.
• Skills are missing: restart the session (/reload) — skills load at session start.
• Reviewer agents are missing: confirm chorus-pi is installed and Pi was restarted; the reviewer agents ship inside the package (no separate sub-agents install, no manual copy).
• Connection is unauthorized: re-check CHORUS_URL / CHORUS_API_KEY (or the .mcp.json Bearer), then restart Pi.
• Tool names look doubled (chorus_chorus_checkin): pi-mcp-adapter prefixes tools with the server name in gateway mode. Call mcp({ tool: "chorus_chorus_checkin" }), or set "toolPrefix": "none" on the chorus server to use the native chorus_* names.

For general connection problems, see Troubleshooting.