[Pi コーディングエージェント](https://pi.dev)は公式の Chorus 統合で、公開された npm パッケージ
**`@chorus-aidlc/chorus-pi`** として配布されます。Chorus のワークフロースキル、読み取り専用の
レビュー用サブエージェント、Pi 公式の `subagent` ツール、そしてセッション対応の拡張フックを、
Pi ネイティブの拡張・スキル・エージェントの仕組みを通じて提供し、いずれも一度の `pi install`
でインストールされます。

Pi は **起動可能な `--agent pi` デーモンバックエンド**として実行することもできます。リモートから
作業が送られると Chorus デーモンがヘッドレスな Pi セッションを起動するため、Pi は Claude Code、
Codex、Kiro と同じように反転した対話のループに参加します。

インストール前に、[エージェントのアクセスを準備する](/ja/guides/administrator-setup/)に従って
API キーを作成します。

## 推奨：自動で設定する

次のコマンドを実行し、Chorus URL とエージェントキーを入力します。

```sh
chorus agents add --agents pi
```

対応する安定版 Pi では `chorus-pi` をインストールし、**MCP 設定も自動で書き込みます**。ネイティブ MCP は `~/.pi/agent/mcp.json`、旧アダプターは `~/.pi/agent/mcp-adapter.json` を使い、どちらも `PI_CODING_AGENT_DIR` に従います。ネイティブ Pi は組み込み MCP を使うため、アダプターや別途の `pi mcp add` は不要です。自動設定に成功したら、下記の手動ステップ 1–3 は不要です。

対話型セッションでも認証情報を手動で export せずに使うには、構成済みエージェントを一覧し、Pi エージェントを名前または UUID で起動します。

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

ランチャーは保存済みの設定から `CHORUS_URL`、`CHORUS_API_KEY`、`CHORUS_AGENT_PROFILE` を渡します。その後、[接続を確認](#接続を確認する)してください。`pi` を直接起動する場合だけ、シェル環境にキーを設定する必要があります。デーモン起動時にも自動で渡されます。既存アダプターや無効化された組み込み MCP がある場合は、下記の移行手順で競合を解消してください。

## MCP バックエンドを選ぶ

インストール前に `pi --version` で安定版を確認します。Chorus 0.21.1 の `chorus agents add --agents pi` はバージョンに応じて構成を選びます。

| Pi のバージョン | MCP バックエンド | インストールするパッケージ |
| --- | --- | --- |
| `>=0.99.0 <2.0.0` | ネイティブ MCP | `@chorus-aidlc/chorus-pi` のみ |
| `0.84.4–0.98.x` | 旧アダプター | `pi-mcp-adapter@5.0.0` と `@chorus-aidlc/chorus-pi` |

それ以前のバージョンと Pi 2.x は非対応で、パッケージ操作は行いません。バージョン不明やプレリリース版ではアダプターを変更せず、MCP 設定完了とも報告しません。対応する安定版を先にインストールしてください。デーモンからの起動には、この範囲内の Pi 0.85.0 以降が必要です。

別のサブエージェントパッケージは不要です。`chorus-pi` に Pi 公式の `subagent` ツールが含まれます。Chorus API キーも用意してください。以下は手動設定の手順です。

## 手動ステップ 1：環境変数を設定する

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

対話型 Pi を起動するシェルで設定します。インストーラーは Pi の env ファイルには保存しません。`CHORUS_URL` はルート URL または完全な `/api/mcp` エンドポイントです。構成済みエージェントを選ぶ場合は `CHORUS_AGENT_PROFILE` も設定します。デーモン起動時には自動で渡されます。

明示的な環境変数が優先されます。Chorus 拡張はセッションやチェックイン用に以下の対応するグローバル MCP ファイルも読み取りますが、ネイティブのプロジェクト専用 `.pi/mcp.json` は検出しません。その構成では両方の変数を引き続き設定してください。

## 手動ステップ 2：Pi のバージョンに合わせて MCP を設定する

### ネイティブ MCP：安定版 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
```

保存先は `~/.pi/agent/mcp.json` です。`PI_CODING_AGENT_DIR` でエージェントディレクトリを変更できます。プロジェクト用には `pi mcp add --local` を使います。保存先は `.pi/mcp.json` で、プロジェクトの信頼が必要です。ルートの `.mcp.json` ではありません。

同等のグローバル設定は次のとおりです。

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

ネイティブ MCP の既定は codemode です。直接ツール公開に切り替える必要はありません。`pi mcp list` は組み込み MCP を確認しますが、対話型の `/mcp` は既存アダプターが提供している場合があります。

### 旧アダプター：Pi 0.84.4–0.98.x

`pi install npm:pi-mcp-adapter@5.0.0` を実行します。上の JSON を `~/.pi/agent/mcp-adapter.json`（または `$PI_CODING_AGENT_DIR/mcp-adapter.json`）に保存し、`mcpServers.chorus` 内に `"directTools": true` を追加します。`toolPrefix` の変更は名前だけに作用し、直接ツール公開を有効にはしません。

両バックエンドとも `${CHORUS_API_KEY}` を解決します。実際のキーは環境変数に保持してください。adapter5 は旧設定の検出やインポートにも対応しますが、旧グローバル `mcp.json` は主設定ファイルではありません。

`chorus agents add` は既存の直接ツール設定や他のサーバー、設定を保持します。旧アダプターの主設定がなければ、旧グローバル `mcp.json` を新しい主設定にコピーし、元ファイルは残します。既存の主設定を優先し、壊れたファイルや読み取れないファイルは上書きしません。生成する Chorus ヘッダーは実際のキーではなく環境変数を参照します。

### 既存アダプターの更新と移行

`chorus upgrade --plugins` と `chorus init --update-installed` は対象となる Chorus コンポーネントだけを更新し、全拡張や Pi 本体は更新しません。旧アダプターは検証済みの `5.0.0` 固定を保持し、latest にはしません。他のアダプター制約や Chorus の固定版・範囲も保持するため、設定や最新版への更新が未完了になることがあります。

ネイティブ対応環境では、既存アダプターや `-builtin:mcp` 拡張フィルターについて警告するだけです。ネイティブ MCP を選ぶ場合は、グローバル `~/.pi/agent/settings.json`（`PI_CODING_AGENT_DIR` に従う）とプロジェクトの `.pi/settings.json` を確認し、元のスコープでのみアダプターとそのフィルターを削除します。他の設定は保持してください。`pi remove npm:pi-mcp-adapter` はグローバル npm インストール用で、プロジェクトの項目には適用しません。Pi を再起動し、実際の MCP ツールを確認します。設定を書くだけでは接続の回復は保証されません。

## 手動ステップ 3: chorus-pi パッケージをインストールする

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

インストールはこれで完了です。`subagent` ツールはパッケージ内に同梱されており、3 つのレビュアー
エージェントはパッケージ自身の `agents/` ディレクトリから直接検出されます。別個のサブエージェント
依存関係は**なく**、エージェントファイルを `~/.pi/agent/agents/` へ手動でコピーする必要も
**ありません**。拡張、スキル、レビュアーエージェントを読み込むために、Pi を再起動します
（`/reload` または新しいセッション）。

`chorus-pi` をローカルで開発していますか？その場合はリポジトリのチェックアウトからインストール
します：`pi install ./packages/chorus-pi`。

## 接続を確認する

Pi を再起動し、`/mcp` を確認して、Pi に `chorus_checkin` の呼び出しを依頼します。応答が想定した
エージェントの身元と権限を示すこと、そして最初のターンでチェックイン情報とともに
`# Chorus Plugin — Active` コンテキストが報告されることを確認します。`/skill:chorus` と入力して
スキルが読み込まれたことを確認し、`/subagents` で `chorus-proposal-reviewer` を確認します。

## 機能

- **14 のスキル**が AI-DLC の全段階を駆動します。`/skill:chorus`、`/skill:idea`、`/skill:proposal`、
  `/skill:develop`、`/skill:review`、`/skill:quick-dev`、`/skill:yolo`、`/skill:brainstorm`、
  `/skill:orchestrate`、`/skill:docs`、`/skill:chorus-cli`、加えて `openspec-aware`、`spec-lite`、
  `research` サブ手順。`research` は idea スキルと proposal スキルが呼び出す短い事実調査で、
  着想の [**リサーチ** 操作](/ja/guides/capture-an-idea/#開発の前にリサーチを依頼する)が実行するのもこれです。
- **3 つの読み取り専用レビュー用サブエージェント** — `chorus-proposal-reviewer`、
  `chorus-task-reviewer`、`chorus-code-reviewer` — はパッケージ相対で検出され（コピー不要）、
  `subagent` ツールを介して起動されます。これらは `VERDICT` コメントを投稿して停止します。
  コミュニティの `pi-subagents` パッケージのもとでは、呼び出しで直接指定された Chorus のレビュアーと
  ワーカーは、その呼び出しが `async: false` を求めていてもバックグラウンドで実行されます。そこではフォアグラウンドの子が
  Chorus のツールに到達できないためです。
- **Pi 公式の `subagent` ツール**は `extensions/subagent/`（Pi のリファレンスパターン）に同梱されているため、
  第三者のサブエージェントパッケージは不要です。さらにコミュニティの **`pi-subagents` パッケージ
  （nicobailon）と共存**します。両者とも `subagent` という名前のツールを登録するため、
  `settings.packages` フィルターで同梱版を除外します。`chorus-pi` のセッションライフサイクルは、
  そのパッケージによる**非同期 / detached** なサブエージェント実行も、同梱版のブロッキング実行とあわせて追跡します。
  フィルターと設定は [`chorus-pi` README](https://www.npmjs.com/package/@chorus-aidlc/chorus-pi) を参照。
- **セッション対応の拡張**が Pi ネイティブのイベントを購読します（`session_start` →
  `chorus_checkin` + 仕様モードの解決、`subagent` に対する `tool_call` → ワーカーごとの Chorus
  セッション、`tool_result` → ワーカーセッションのクローズ + レビュアーの促し、`session_shutdown`
  → クリーンアップ）。

拡張は環境変数で設定します（Pi にはプラグイン設定 UI がありません）。`CHORUS_SPEC_MODE` で `openspec`、
`lite`、`off` を選べます。未設定の場合、OpenSpec が使用可能ならそれを、そうでなければ spec-lite を使います。従来の
`CHORUS_OPENSPEC_MODE=off` は OpenSpec だけを無効にし、自由形式ではなく `lite` にフォールバックします。
ローカル仕様ファイルが不要なら `CHORUS_SPEC_MODE=off` を使ってください。
[OpenSpec モード](/ja/guides/openspec-mode/)と [Spec-lite モード](/ja/guides/spec-lite-mode/)を参照。
レビューのトグルは引き続き `CHORUS_ENABLE_{PROPOSAL,TASK,CODE}_REVIEWER`（既定 `true`）です。

## Pi を起動可能なデーモンバックエンドとして実行する

Pi は第一級の **起動可能なデーモンバックエンド**です。リモートから作業が送られると
（エージェントへの着想・課題の割り当て、`@mention`、提案の決定）、Chorus デーモンがヘッドレスな Pi
セッションを起動します。

最も簡単なのは `chorus agents add --agents pi` です。Pi のバージョンに合うネイティブ MCP または検証済み旧アダプターを選び、`chorus-pi` をインストールし、`~/.chorus/daemon.json` に Pi を登録します。同意すれば起動時サービスもインストールします。手動で起動する場合：

```bash
chorus daemon --agent pi
```

- デーモンは `PATH` から `pi` 実行ファイルを解決し（`CHORUS_PI_PATH` で上書き可能）、起動ごとに
  ヘッドレスの `pi --mode rpc` プロセスを一つ開始します。起動されたセッションには `CHORUS_URL` /
  `CHORUS_API_KEY` / `CHORUS_AGENT_PROFILE` をエクスポートします。デーモンからの起動には
  **Pi 0.85.0 以降**が必要です。[0.20.0 のデーモン動作](#0200-のデーモン動作)を参照してください。
- Pi には**権限システムがありません**。そのためサンドボックスや skip-permissions フラグは関与
  しません。`chorus` モードでも `yolo` モードでも、デーモンによる Pi の実行方法は同じです。
- デーモンが起動する環境に `chorus-pi` とバージョンに合う MCP 設定を用意してください。ネイティブ Pi にはアダプターは不要です。

デーモンは Chorus 接続（`CHORUS_URL`、`CHORUS_API_KEY`、`CHORUS_AGENT_PROFILE`）を提供しますが、
モデルプロバイダーの認証情報を取得してくれるわけではありません。`~/.chorus/daemon.json` 内のそのエージェントの `env`、
デーモンが継承する環境、またはプロバイダーが対応する認証情報ストアで提供してください。`systemd --user` サービスは
ログインシェルの export を継承しません。モデルと思考の引数、エージェントごとの env、サービスの認証情報、
必要な再起動については[デーモンガイド](/ja/guides/daemon-operations/)を参照してください。

### 0.20.0 のデーモン動作

Chorus 0.20.0 から、Pi の起動はすべて Pi の RPC モードで実行されます。以前のヘッドレスモードへの
フォールバックはないため、デーモンを実行するすべてのホストで Pi を更新してください。

```bash
pi --version                                                # 0.85.0 以降が必要
npm install -g "@earendil-works/pi-coding-agent@>=0.85.0 <2.0.0"       # pi 本体を更新
```

`chorus upgrade --plugins` は対象の Chorus コンポーネントを更新し、Pi 本体は更新しません。旧 adapter5 は前述の固定版を保持します。RPC 通信は Linux の Pi **0.85.1** で検証済みです。

- **古い Pi：** デーモンはその起動をスキップし、上記の更新コマンドをログに出します。Pi のバージョンを
  読み取れない場合は警告を記録し、そのまま起動を試みます。
- **セッションの継続：** 各着想は自分の Pi セッションを保持し、更新前に作られたセッションも
  引き継がれます。Pi が以前のセッション履歴を復元できない場合、起動は新しいセッションで続行され、
  会話に以前の履歴を復元できなかったという通知が表示されます。
- **中断：** Chorus で **中断** を押すと RPC `abort` が送られ、実行中のツールも含めて Pi の現在の実行が停止します。
  Pi が終了コード 0 で終了しても、そのターンは中断として記録されます。`sigintTimeoutMs` の経過後も Pi が動作している場合は、
  従来どおりデーモンが強制停止します。
- **拡張のダイアログ：** 起動中は端末の前に誰もいないため、拡張のダイアログ（select、confirm、
  input、editor）は即座にキャンセルされ、デーモンは `cancelled pi extension <method> dialog` を
  ログに出します。質問には Chorus のコメントか要件詳細化を使ってください。
- **プロセスの探し方：** Pi はプロセス名を `pi` に変更するため、Linux では
  `pgrep -f 'pi --mode rpc'` では見つかりません。`pgrep -x pi -P <daemon-pid>` を使ってください。

## よくある問題

- **MCP サーバーが見つからない**：バージョンに合う設定ファイルを確認します。ネイティブ Pi では `pi mcp list` を実行し、対話型ツールが異なる場合はプロジェクトの信頼、旧アダプター、`-builtin:mcp` フィルターも確認します。
- **スキルやレビュアーがない**：`chorus-pi` のインストールを確認し Pi を再起動します。レビュアーは同梱され、手動コピーや別パッケージは不要です。
- **接続が認証されない**：起動シェルの `CHORUS_URL` と `CHORUS_API_KEY` を確認して Pi を再起動します。共有設定に実際のキーを書かないでください。
- **ツール名が異なる**：推測せず、検出されたスキーマを確認します。ネイティブ MCP は `mcp__chorus__chorus_checkin` など、旧直接ツールは通常 `chorus_chorus_checkin` を使います。`toolPrefix: "none"` は旧版の名前のみを変えます。
- **旧プラグインでワークフロー通知やネイティブ MCP でのレビューが失敗する**：Chorus 0.21.1 以降に更新します。この版は MCP 接頭辞ごとの Pi/dsh 通知と Pi ネイティブ MCP レビュアーの互換性を修正します。レビュアーは判定の投稿以外は読み取り専用です。

一般的な接続問題は[接続のトラブルシューティング](/ja/guides/troubleshooting/)を参照してください。