The [Pi coding agent](https://pi.dev) 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](/guides/administrator-setup/).

## Recommended: configure automatically

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

```sh
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:

```sh
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](#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

```bash
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`

```bash
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:

```json
{
  "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

```bash
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](/guides/capture-an-idea/#ask-for-research-before-development) 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](https://www.npmjs.com/package/@chorus-aidlc/chorus-pi)
  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](/guides/openspec-mode/) and [Spec-lite mode](/guides/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:

```bash
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](#daemon-behavior-in-0200).
- 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](/guides/daemon-operations/) 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:

```bash
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](/guides/troubleshooting/).