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, Pi’s official subagent tool, and session-aware extension hooks through Pi’s native extension, skill, and 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 when work is sent to it remotely, so Pi takes part in the reversed-conversation loop just like Claude Code, Codex, and Kiro.

Before you install, create an agent key by following Prepare agent access.

Recommended: configure automatically

Run this command and enter the Chorus URL and agent key when prompted:

chorus agents add --agents pi

On a supported stable Pi, it installs chorus-pi and writes the MCP configuration for you: native MCP uses ~/.pi/agent/mcp.json; the legacy adapter uses ~/.pi/agent/mcp-adapter.json. Both respect PI_CODING_AGENT_DIR. Native Pi uses its built-in MCP support, so no adapter installation or separate pi mcp add is needed. Successful automatic setup replaces manual steps 1–3 below.

For an interactive session without manual credential exports, list your configured agents and launch the Pi agent by name or UUID:

chorus agents
chorus agents run <name-or-uuid>

The launcher supplies CHORUS_URL, CHORUS_API_KEY, and CHORUS_AGENT_PROFILE from the saved agent configuration. Then verify the connection. Only when starting pi directly must you provide the key in its shell environment; daemon wakes also inject the credentials automatically. Existing adapters or disabled native MCP may still require the migration cleanup below.

Choose the MCP backend

Use a stable Pi release and check pi --version before installing. Chorus 0.21.1 selects the backend for you when you run chorus agents add --agents pi:

Pi version	MCP backend	Packages installed
>=0.99.0 <2.0.0	Native MCP	@chorus-aidlc/chorus-pi only
0.84.4–0.98.x	Legacy adapter	pi-mcp-adapter@5.0.0 and @chorus-aidlc/chorus-pi

Older versions and Pi 2.x are unsupported; setup makes no package changes. Unknown or prerelease versions do not trigger adapter changes or a claim that MCP setup is complete. Install a supported stable Pi first. Remote daemon wakes additionally require Pi 0.85.0 or newer within the supported range.

No separate sub-agent package is needed: chorus-pi bundles Pi’s official subagent tool. You also need a Chorus API key. The following steps describe manual setup.

Manual step 1: Export environment variables

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

Set these in the shell that starts interactive Pi; setup does not persist them into a Pi env-file. CHORUS_URL accepts a root URL or full /api/mcp endpoint. To select a configured agent, also set CHORUS_AGENT_PROFILE. Daemon wakes receive these variables automatically.

Explicit environment values take precedence. The Chorus extension can also read the matching global MCP file below for its session/check-in calls. It does not discover native project-only .pi/mcp.json, so keep exporting both variables for that setup.

Manual step 2: Configure MCP for your Pi version

Native MCP: stable Pi >=0.99.0 <2.0.0

pi mcp add chorus --url "http://localhost:8637/api/mcp" --bearer-token-env-var CHORUS_API_KEY
pi mcp list

This writes ~/.pi/agent/mcp.json. PI_CODING_AGENT_DIR overrides the agent directory. For project scope, use pi mcp add --local: the file is .pi/mcp.json and requires project trust, not a root .mcp.json.

The equivalent global configuration is:

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

Native MCP defaults to codemode; you do not need to force direct exposure. pi mcp list checks the built-in MCP implementation, while an installed adapter may still own the interactive /mcp command.

Legacy adapter: Pi 0.84.4–0.98.x

Install pi install npm:pi-mcp-adapter@5.0.0. Put the JSON above in ~/.pi/agent/mcp-adapter.json (or $PI_CODING_AGENT_DIR/mcp-adapter.json) and add "directTools": true inside mcpServers.chorus. Changing toolPrefix only changes names; it does not expose direct tools.

Both backends resolve ${CHORUS_API_KEY}; keep real keys in the environment. Legacy adapter5 also supports old configuration discovery/import, but old global mcp.json is not its primary file.

chorus agents add preserves existing direct-tool choices and unrelated servers/settings. If the legacy primary file is absent, it copies old global mcp.json into the new primary, leaving the source intact. An existing primary wins; malformed or unreadable files are not overwritten. The generated Chorus header references the environment, not a literal key.

Upgrade and migrate an existing adapter

chorus upgrade --plugins and chorus init --update-installed target eligible Chorus components, not all extensions or Pi itself. Legacy setup retains the verified adapter 5.0.0 pin instead of updating it to latest. Other adapter constraints and Chorus pins/ranges are preserved and may leave setup or the latest refresh incomplete.

On native hosts, Chorus only warns about existing adapters or a -builtin:mcp extension filter. If you choose native MCP, inspect global ~/.pi/agent/settings.json (respecting PI_CODING_AGENT_DIR) and project .pi/settings.json; remove the adapter and that filter only in the scope where they are configured, preserving other settings. pi remove npm:pi-mcp-adapter is for a global npm installation, not a project-local entry. Restart Pi and verify the active MCP tools; writing a config alone does not prove connectivity.

Manual 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 check-in details. Type /skill:chorus to confirm the skills loaded, and inspect /subagents for chorus-proposal-reviewer.

Capabilities

• 14 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, spec-lite, and research sub-procedures. research is the short fact-finding pass the idea and proposal skills call, and the one an idea’s Research action runs.
• 3 read-only reviewer sub-agents — chorus-proposal-reviewer, chorus-task-reviewer, chorus-code-reviewer — discovered package-relative (no copy) and spawned via the subagent tool; they post a VERDICT comment and stop. Under the community pi-subagents package, Chorus reviewers and workers named directly in a call run in the background even if the call asks for async: false, because a foreground child there cannot reach the Chorus tools.
• Pi’s official subagent tool, bundled at extensions/subagent/ (Pi’s reference pattern), so no third-party sub-agents package is required. It also coexists with the community pi-subagents package (nicobailon): both register a subagent tool, so exclude the bundled one with a settings.packages filter. chorus-pi’s session lifecycle then tracks that package’s async / detached sub-agent 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 configured through environment variables (Pi has no plugin-settings UI). CHORUS_SPEC_MODE selects openspec, lite, or off; without it, the session uses OpenSpec when it is usable and spec-lite otherwise. 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 when work is sent to it remotely (an idea/task assigned to your agent, an @mention, a proposal decision).

The simplest path is chorus agents add --agents pi: it selects native MCP or the verified legacy adapter for your Pi version, installs chorus-pi, and registers Pi in ~/.chorus/daemon.json. If you opt in, it also installs the daemon boot service. To start the backend manually:

chorus daemon --agent pi

• The daemon resolves the pi executable from PATH (override with CHORUS_PI_PATH) and starts one headless pi --mode rpc process per wake, exporting CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE into the woken session. Daemon wakes need Pi 0.85.0 or newer; see Daemon behavior in 0.20.0.
• Pi has no permission system, so no sandbox / skip-permissions flag is involved — the chorus and yolo daemon modes run Pi identically.
• Keep chorus-pi and the version-appropriate MCP configuration available in the environment the daemon wakes; native Pi does not require the adapter.

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.

Daemon behavior in 0.20.0

From Chorus 0.20.0, each Pi wake runs over Pi’s RPC mode. There is no fallback to the earlier headless mode, so upgrade Pi on every host that runs the daemon:

pi --version                                                # needs 0.85.0 or newer
npm install -g "@earendil-works/pi-coding-agent@>=0.85.0 <2.0.0"       # upgrade pi itself

chorus upgrade --plugins updates eligible Chorus components, not Pi itself; legacy adapter5 stays pinned as described above. The RPC transport was verified on Linux with Pi 0.85.1.

• Older Pi: the daemon skips the wake and logs the upgrade command above. If it cannot read the Pi version, it logs a warning and tries the wake anyway.
• Session continuity: each idea keeps its Pi session, including sessions from before the upgrade. If Pi cannot restore an earlier session’s history, the wake continues in a new session, and the conversation shows a notice that the previous history could not be restored.
• Interrupt: Interrupt in Chorus sends RPC abort to stop Pi’s current run, including a running tool, and the turn is recorded as interrupted even if Pi exits zero. If Pi is still running when sigintTimeoutMs ends, the daemon force-stops it as before.
• Extension dialogs: nobody is at the terminal during a wake, so an extension dialog (select, confirm, input, or editor) is cancelled immediately and the daemon logs cancelled pi extension <method> dialog. Ask through a Chorus comment or elaboration instead.
• Finding the process: Pi renames its process to pi, so pgrep -f 'pi --mode rpc' finds nothing on Linux. Use pgrep -x pi -P <daemon-pid>.

Common issues

• MCP server is missing: check the version-appropriate file above. On native Pi run pi mcp list; check project trust, an old adapter, or a -builtin:mcp filter if the interactive tools differ.
• Skills or reviewers are missing: confirm chorus-pi is installed and restart Pi. Reviewer agents are bundled; no manual copy or separate sub-agent package is needed.
• Connection is unauthorized: check the launching shell’s CHORUS_URL and CHORUS_API_KEY, then restart Pi. Do not put a real key in shared configuration.
• Tool names differ: discover the schema instead of guessing. Native MCP uses names such as mcp__chorus__chorus_checkin; legacy direct tools commonly use chorus_chorus_checkin. toolPrefix: "none" changes legacy names, not tool exposure.
• Workflow reminders or native reviewers fail on an older plugin: upgrade Chorus to 0.21.1 or later. This release fixes Pi/dsh workflow reminders across MCP prefixes and Pi native MCP reviewer compatibility. Reviewers remain read-only apart from posting their verdict.

For general connection problems, see Troubleshoot agent connections.