Claude Code에는 공식 Chorus 플러그인이 있습니다. 대화형 Claude Code 세션에서 Chorus 도구와
워크플로 스킬을 지원하며, 지원되는 Chorus 데몬 백엔드로도 실행할 수 있습니다.

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

## 백그라운드 자식 에이전트(0.22.0)

Claude daemon 실행은 주 턴 이후 기본 60분(`3600000` ms) 동안 자식을 기다립니다. `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`가 `CHORUS_CLAUDE_BG_WAIT_CEILING_MS`보다 우선하며 전체 실행 제한이 아닙니다. 부모는 완료 결과를 수집하거나 자식을 명시적으로 중지한 뒤 턴을 끝내야 합니다. 강제 종료된 자식이 있으면 실제 종료 코드가 0이어도 비정상이며 시작점 아이디어나 작업에 댓글을 게시하려고 합니다. 상태 복구나 새 자동 재시도는 없습니다. 0/빈 값 위험, 설정, 진단은 [daemon 시간 제한 설정](/ko/guides/daemon-operations/)을 참조하세요.

## 플러그인 설치

가장 빠른 방법은 `chorus` CLI로, 플러그인을 설치하고 인증 정보를 대신 저장해 줍니다.

```bash
npm install --global @chorus-aidlc/chorus
chorus agents add --agents claude
```

프롬프트가 나오면 Chorus URL과 에이전트 키를 입력합니다. `chorus agents add`는 `claude plugin marketplace add` / `claude plugin install`을 대신 실행하고, `CHORUS_URL`, `CHORUS_API_KEY`, `CHORUS_AGENT_PROFILE`를 사용자 전역 `~/.claude/settings.json`의 `env` 블록에 쓰므로, 대화형 Claude Code 세션이 수동 환경 설정 없이 인증합니다. 그 뒤 Claude Code를 재시작하세요.

직접 설치하려면, 시작하는 셸에서 인증 정보를 설정합니다.

```bash
export CHORUS_URL="https://chorus.example.com"
export CHORUS_API_KEY="cho_REDACTED"
```

그런 다음 Claude Code 안에서 플러그인을 추가합니다.

```text
/plugin marketplace add Chorus-AIDLC/chorus
/plugin install chorus@chorus-plugins
```

설치 후 Claude Code를 재시작합니다.

## 원격 시작 활성화

대화형 Claude Code 세션에서만 Chorus를 사용한다면 이 섹션을 건너뛰세요. 그렇지 않다면
[에이전트 런타임 연결](/ko/guides/operator-onboarding/)에 따라 백엔드로 `claude-code`를 선택합니다.
[Chorus 데몬 운영](/ko/guides/daemon-operations/)으로 온라인 상태를 유지하기 전에, 포그라운드에서
연결을 확인하세요.

## 0.20.0의 데몬 동작

깨울 때마다 하나의 `claude -p` 프로세스를 시작하고 턴이 끝나면 종료하는 방식은 유지됩니다. Chorus는 이제 양방향 **stream-json** 입출력을 사용하며 제어 응답을 위해 연결을 열어 둡니다. 기존 세션과 `claude --resume`은 계속 사용할 수 있습니다. 일반 텍스트 대체 경로나 전송 전환 옵션은 없습니다. Linux에서 Claude Code **2.1.283 및 2.1.284**로 실제 실행을 검증했습니다. 이는 검증을 마친 버전일 뿐, 모든 Claude Code 릴리스와의 호환을 보장하는 최소 버전은 아닙니다.

- **중단**: 먼저 프로토콜 중단을 보냅니다. `sigintTimeoutMs` 안에 멈추지 않으면 프로세스 트리를 강제로 종료합니다. 기본값은 기존과 같은 10초입니다.
- **제한 도구**: `--chorus-only` 모드에서는 Chorus 외 도구가 명시적인 거부 응답을 받으며, 이 응답은 에이전트에게 Chorus 도구를 사용하거나 Chorus 댓글로 질문하도록 안내합니다. 로그에는 거부된 도구 이름만 기록하고 입력은 기록하지 않습니다. YOLO 동작은 유지됩니다.
- **질문**: 데몬 실행은 YOLO를 포함해 모두 `AskUserQuestion`을 비활성화합니다. 터미널에서 답할 사람이 없으므로, 에이전트는 Chorus 댓글이나 요구사항 구체화로 질문해야 합니다. 대화형 Claude Code 세션의 질문 흐름은 그대로입니다.

업그레이드 후에는 호스트에 설치된 실제 Claude Code 버전으로 체크인, 후속 턴, 중단 및 재개를 확인하세요. 프로토콜 문제는 [데몬 로그](/ko/guides/daemon-operations/), 계속 진행하는 방법은 [세션 중단과 재개](/ko/guides/session-recovery/)를 참고하세요.

## 연결 확인

Claude Code에서 `/plugin list`를 실행해 `chorus@chorus-plugins`가 활성화되어 있는지 확인합니다.
그런 다음 Claude Code에 `check in to chorus`를 요청합니다. 성공하면 응답이 연결된 에이전트와
그 권한을 보여 줍니다.

데몬 모드에서는 Chorus의 **설정 → 에이전트**를 열고 예상한 호스트와 작업 디렉터리가 온라인인지
확인합니다.

## 기능과 제한

- 플러그인은 Chorus MCP 도구, 워크플로 스킬, 그리고 수명 주기 통합을 제공합니다.
- 데몬 모드는 원격 시작, 후속 지시, 중단, 재개를 지원합니다.
- 원격 작업은 등록된 작업 디렉터리 안에서 로컬 운영체제 사용자가 사용할 수 있는 모든 것에 접근할
  수 있습니다. 신뢰하는 디렉터리만 등록하세요.

공통 운영 절차는 [원격 에이전트에서 작업 시작](/ko/guides/remote-control/)과
[세션 중단과 재개](/ko/guides/session-recovery/)를 사용하세요.

## 터미널에서 재개하기

자신의 터미널에서 진행 중인 대화를 넘겨받으려면, 채팅 UI에서 해당 세션 ID를 복사한 뒤
(대화 기록 헤더의 **세션 ID 복사**), 그 대화의 작업 디렉터리에서 실행합니다.

```bash
claude --resume <sessionId>
```

복사한 ID는 Chorus가 세션을 재개할 때 Claude Code에 전달하는 것과 같은 ID입니다. Claude Code
백엔드에서는 이 ID가 세션이 속한 아이디어의 UUID입니다. 전체 흐름은
[세션 중단과 재개](/ko/guides/session-recovery/#터미널에서-이어받기)를 참고하세요.

## 자주 발생하는 문제

- **플러그인이 나타나지 않음:** Claude Code를 재시작한 뒤 `/plugin list`를 확인합니다.
- **체크인이 승인되지 않음:** 에이전트 키를 만들거나 교체한 다음 `chorus agents add`를 다시
  실행하고(또는 `~/.claude/settings.json`의 `env` 블록을 업데이트하고) Claude Code를 재시작합니다.
- **데몬이 오프라인:** `chorus daemon status`를 실행한 뒤
  [에이전트 연결 문제 해결](/ko/guides/troubleshooting/)을 참고합니다.
- **잘못된 작업 디렉터리가 온라인으로 표시됨:** 의도한 절대 경로의 `--cwd` 값으로 데몬을 다시 설치합니다.

## 서브에이전트 세션

플러그인이 관리하는 서브에이전트 세션은 에이전트 유형을 이름으로 사용합니다. 같은 유형의 병렬 서브에이전트는
하나의 Chorus 세션을 공유할 수 있으며, 세션은 마지막 서브에이전트가 끝날 때까지 열려 있습니다.
따라서 하나가 먼저 종료되어도 아직 실행 중인 다른 서브에이전트의 작업 추적이 끊기지 않습니다.