[Pi 코딩 에이전트](https://pi.dev)용 공식 Chorus 통합은 게시된 npm 패키지
**`@chorus-aidlc/chorus-pi`** 형태로 배포됩니다. Pi의 네이티브 확장·스킬·에이전트 메커니즘을 통해
Chorus 워크플로 스킬, 읽기 전용 검토용 서브에이전트, Pi의 공식 `subagent` 도구, 그리고 세션
인식 확장 훅을 제공하며, 한 번의 `pi install`로 설치됩니다.

Pi는 **깨울 수 있는 `--agent pi` 데몬 백엔드**로도 실행할 수 있습니다. Chorus 데몬이 원격으로
작업을 받으면 헤드리스 Pi 세션을 깨우므로, Pi는 Claude Code, Codex, Kiro와 마찬가지로 뒤집힌
대화 루프에 참여합니다.

설치 전에 [에이전트 액세스 준비](/ko/guides/administrator-setup/)에 따라 에이전트 키를
만드세요.

## 권장: 자동 구성

다음 명령을 실행하고 안내에 따라 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단계를 반복하지 않아도 됩니다.

대화형 세션에서도 인증 정보를 수동으로 내보내지 않으려면 구성된 에이전트 목록에서 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` 도구는 패키지 안에 포함되어 있고, 세 개의 검토 에이전트는
패키지 자체의 `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 스킬이 호출하는 짧은 사실 조사 단계이며,
  아이디어의 [**리서치** 기능](/ko/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 모드](/ko/guides/openspec-mode/)와
[Spec-lite 모드](/ko/guides/spec-lite-mode/)를 참고하세요. 검토 토글은 계속
`CHORUS_ENABLE_{PROPOSAL,TASK,CODE}_REVIEWER`(기본 `true`)입니다.

## Pi를 깨울 수 있는 데몬 백엔드로 실행

Pi는 정식 지원되는 **깨울 수 있는 데몬 백엔드**입니다 — 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에는 **권한 시스템이 없으므로**, 샌드박스 / 권한 건너뛰기 플래그가 적용되지 않습니다 —
  `chorus` 및 `yolo` 데몬 모드는 Pi를 동일하게 실행합니다.
- 데몬이 실행하는 환경에 `chorus-pi`와 버전에 맞는 MCP 구성을 유지하세요. 네이티브 Pi는 어댑터가 필요하지 않습니다.

데몬은 Chorus 연결(`CHORUS_URL`, `CHORUS_API_KEY`, `CHORUS_AGENT_PROFILE`)을 제공하지만 모델 제공자의
인증 정보를 대신 얻어 주지는 않습니다. `~/.chorus/daemon.json`에 있는 해당 에이전트의 `env`, 데몬이 상속하는 환경,
또는 제공자가 지원하는 인증 정보 저장소로 제공하세요. `systemd --user` 서비스는 로그인 셸의 export를 상속하지
않습니다. [데몬 가이드](/ko/guides/daemon-operations/)에서 모델·사고 인수, 에이전트별 env, 서비스 인증 정보,
필요한 재시작을 확인하세요.

### 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"`은 이전 도구의 이름만 바꿉니다.
- **이전 플러그인의 워크플로 알림이나 네이티브 검토 실패**: Chorus 0.21.1 이상으로 업그레이드하세요. 이 릴리스는 MCP 접두사별 Pi/dsh 알림과 Pi 네이티브 MCP 검토 호환성을 수정합니다. 검토 에이전트는 판정 게시 외에는 읽기 전용입니다.

일반 연결 문제는 [에이전트 연결 문제 해결](/ko/guides/troubleshooting/)을 참고하세요.