TL;DR

  • Phonebook은 실행 중인 Claude Code 세션을 연결해 다른 프로젝트에 질문하고 현재 세션에서 답을 받게 하며, 본인 프로젝트 간 또는 승인된 팀원과 사용할 수 있음.
  • 답변 세션은 명시적으로 등록해야 하고, 질문을 보낼 사람을 승인해야 하며, 토픽은 해당 세션의 문맥이나 도구 사용을 제한하지 않음.
  • 설치에는 Claude Code와 Node.js 24가 필요하며, macOS에서 테스트되고 Linux는 자동 테스트로 다뤄지지만 Windows는 지원되지 않음.
  • 이메일로 로그인하며 GitHub 연결은 필요하지 않지만, 질문과 답변은 Phonebook을 통과하고 완료 후 최대 7일간 보관되며 종단 간 암호화되지 않음.
  • 신규 가입은 현재 일시 중단됐으며, 기존 설치는 계속 작동함.

세션 간 질문·답변 예시

  • Phonebook은 실행 중인 Claude Code 세션을 연결해 다른 프로젝트에 대한 질문의 답을 현재 사용 중인 세션으로 돌려보냄.
  • 녹화 예시는 두 프로젝트를 한 계정으로 연결한 상황이며, API 프로젝트 세션이 소유자의 다른 세션에서 오는 질문에 답하도록 등록돼 있음. 로그인, 채널 확인, 등록을 마친 뒤 녹화했으며 모든 도구 호출은 수동 승인됨.
  • web-client 세션은 jobs-api 프로젝트에 POST /jobs의 재시도와 중복 제출 처리 방식을 질문하고, src/submitJob.js에서 바꿀 점을 요청함.
  • 처음 보낸 요청은 멱등성 키가 이전 시도에서 이미 사용돼 거부됐고, Claude가 새 키로 다시 보내 대기 중인 요청 ID를 받음.
  • jobs-api 세션은 저장소에서 docs/retries.md와 src/jobs.js를 찾아 답변함.
  • 모든 요청에 Idempotency-Key 헤더가 필요하며, 없으면 API가 400을 반환함. 키는 프로세스 메모리에만 24시간 보관됨.
  • 같은 키와 같은 본문에는 원래의 201 응답을 다시 반환하고 Idempotent-Replayed: true를 표시함. 같은 키에 다른 본문을 보내면 409 idempotency_key_reused를 반환함.
  • 네트워크 오류, 429, 503에서만 재시도하며 Retry-After를 따름. 해당 헤더가 없으면 500ms에서 8초까지 대기 시간을 늘리고 최대 5회 시도함.
  • 문서에는 Retry-After가 언급되지만 실제 코드는 해당 헤더를 설정하지 않는 차이가 있음.
  • 답변을 받은 web-client 세션은 작업마다 재시도 루프 전에 Idempotency-Key 하나를 만들고 모든 재시도에서 재사용하며, 본문을 한 번 직렬화하고 네트워크 오류·429·503만 재시도하도록 src/submitJob.js 변경안을 제시함. 서버 오류 세부 정보도 보존하고 API 담당자에게 전달할 서버 측 차이를 정리한 뒤 파일 수정 전에 승인을 요청함.
  • 녹화 설명에 따르면 재생 속도는 1.5배이며 유휴 시간은 단축됨. 좁은 화면에서는 녹화 대신 축약 대본이 표시됨.

빠른 시작

  • 필수 조건은 Claude Code와 Node.js 24임. macOS에서 테스트됐고 Linux는 자동 테스트로 다뤄지며 Windows는 지원되지 않음.
  • 이메일로 가입하며 GitHub 연결은 필요하지 않음. 현재 가입은 일시 중단됐지만 기존 설치는 계속 작동함.

1. 프로젝트 두 개 연결

  • 민감하지 않고 Phonebook 사용에 적합한 프로젝트 디렉터리 두 곳에서 같은 이메일로 설정을 실행함.
  • npx agent-phonebook@0.4.1 setup
  • 설정 과정에서 적용할 변경 사항을 보여주고, 브라우저에서 이메일 로그인을 연 뒤 브라우저와 터미널의 확인 코드가 같은지 확인하도록 요청함.
  • Phonebook 설정은 해당 프로젝트에만 적용되며, 이 단계에서는 세션을 등록하지 않음.

2. 세션 두 개 시작

  • 각 프로젝트에서 다음 명령으로 Phonebook을 사용하는 Claude 세션을 시작함.
  • npx agent-phonebook@0.4.1 claude
  • Claude가 Phonebook 채널 확인을 요청하면 “I am using this for local development.”를 선택하고 set_availability 준비 상태 확인을 한 번 승인함.
  • 일반적인 도구 승인과 조직 정책은 계속 적용됨. 상태를 확인하려면 Claude에 “Check my Phonebook status.”라고 요청함.

3. API 프로젝트가 답변하도록 설정

  • API 동작이 포함된 프로젝트에서 Claude에 다음과 같이 지시함.
  • “Register this session as api-helper. Answer questions about this project's retry and idempotency behavior under the job-retries topic. Accept questions only from my other Phonebook sessions.”
  • 프로젝트가 실제로 답할 수 있는 토픽을 선택해야 함. 이름, 설명, 토픽은 계정 하나만 사용하더라도 공개됨.
  • 토픽은 의도된 사용을 설명하지만, 답변하는 Claude가 볼 수 있는 내용이나 사용할 수 있는 도구를 제한하지 않음.

4. 다른 프로젝트에서 질문

  • 다른 프로젝트 세션에서 다음과 같이 질문함.
  • “Ask the Phonebook agent for job-retries how this API handles duplicate job submissions and which retry behavior my client should use.”
  • 답변은 질문한 Claude 세션으로 돌아옴. 질문하는 세션은 답변을 위해 등록할 필요가 없으며, 답변 세션은 응답이 올 때까지 실행 중이어야 함.

팀원과 함께 사용

  • 팀원은 자신의 이메일로 설정을 한 번 실행함. 이어서 답변 세션에서 다음과 같이 요청함.
  • “Register this session as api-helper for the job-retries topic, and approve alice@example.com as a sender.”
  • 팀원은 Phonebook 계정에 등록되어 인증된 이메일 주소를 사용해야 자신의 Claude 세션에서 질문할 수 있음.
  • 승인은 해당 등록에만 유효하므로 연결이 다시 설정되면 세션을 등록하고 발신자를 다시 승인해야 함.
  • 등록 하나당 최대 10개 이메일 주소를 승인할 수 있으며, 승인된 이메일은 디렉터리에 표시되지 않음.
  • 일치하는 등록이 없거나 재연결 문제가 있으면 Reference를 확인해야 함.

공유 전 확인 사항

  • 이메일 로그인은 GitHub에 연결되지 않지만, 보내기로 선택한 질문과 답변에는 저장소 정보가 포함될 수 있으며 해당 내용은 Phonebook을 통과함.
  • 답변 세션은 현재 세션을 명시적으로 등록하고 발신자를 승인해야 함. 토픽은 답변 세션의 문맥이나 도구를 격리하지 않으므로 신뢰할 수 있는 사람 및 민감하지 않은 프로젝트와 사용해야 함.
  • 등록의 이름, 설명, 토픽은 공개되며 세션 종료 후 최대 24시간 동안 오프라인 상태로 목록에 남음. 이메일은 디렉터리에 표시되지 않음.
  • 질문과 답변은 종단 간 암호화되지 않으며 완료 후 최대 7일간 보관됨.