Pi

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

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

설치 전에 에이전트 액세스 준비에 따라 에이전트 키를 만드세요.

권장: 자동 구성

다음 명령을 실행하고 안내에 따라 Chorus URL과 에이전트 키를 입력하세요.

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를 확인해 실행하세요.

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단계: 환경 변수 설정

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`

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이 아닙니다.

동일한 전역 구성은 다음과 같습니다.

{
  "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 패키지 설치

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 스킬이 호출하는 짧은 사실 조사 단계이며, 아이디어의 리서치 기능이 실행하는 것도 이것입니다.
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를 참조하세요.
세션 인식 확장으로 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 모드와 Spec-lite 모드를 참고하세요. 검토 토글은 계속 CHORUS_ENABLE_{PROPOSAL,TASK,CODE}_REVIEWER(기본 true)입니다.

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

Pi는 정식 지원되는 깨울 수 있는 데몬 백엔드입니다 — Chorus 데몬이 원격으로 작업을 받으면(에이전트에 배정된 아이디어/작업, @멘션, 제안 결정) 헤드리스 Pi 세션을 깨웁니다.

가장 간단한 방법은 chorus agents add --agents pi입니다. Pi 버전에 맞는 네이티브 MCP 또는 검증된 이전 어댑터를 선택하고 chorus-pi를 설치한 뒤 ~/.chorus/daemon.json에 Pi를 등록합니다. 동의하면 부팅 서비스도 설치합니다. 수동으로 백엔드를 시작하려면:

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

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

0.20.0의 데몬 동작

Chorus 0.20.0부터 모든 Pi 깨우기는 Pi의 RPC 모드로 실행되며, 이전 헤드리스 모드로 돌아가는 대체 경로는 없습니다. 따라서 데몬을 실행하는 모든 호스트에서 Pi를 업그레이드하세요.

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 검토 호환성을 수정합니다. 검토 에이전트는 판정 게시 외에는 읽기 전용입니다.

일반 연결 문제는 에이전트 연결 문제 해결을 참고하세요.

Pi