Agent Bridge 첫 사용: Codex↔Claude
현재 alpha의 조건을 먼저 확인하고, 설치 선택·등록·route·실제 수신 확인·종료를 한 쌍의 작은 실습으로 따라갑니다. 모델 호출과 운영 변경은 사람이 범위를 정합니다.
문서 검토 2026-11-05 · Alpha · macOS · UNLICENSED
먼저 조건 확인
현재 배포는 0.1.0-alpha.1입니다. 설치는 macOS로 제한되며 Node >=26.5.1 <27이 필요합니다. Windows/Linux에서는 설치를 진행하지 마세요. Kit은 필수가 아닙니다.
UNLICENSED: 공개 다운로드가 가능해도 오픈소스 라이선스가 부여된 것은 아닙니다. alpha 사용과 라이선스 조건을 검토하세요. 실제 여러 세션 쌍의 격리, Claude/AGY 수신 측 crash 경계와 장시간 운영은 미검증입니다. 간헐적 테스트 실패와 store race 가능성도 미해결로 공개돼 있습니다.
선택한 실습 폴더의 터미널. 모든 placeholder를 실제 값으로 바꾸고 결과를 읽은 뒤 진행하세요.
uname -s node --version npm --version git --version
두 선택과 변경 범위를 정하기
가이드 기준 0.1.0-alpha.1 사용 또는 설치 시점 최신 릴리스 검토 중 선택하세요. 최신도 alpha일 수 있습니다. Node/npm/Git/Bridge의 현재·제안 버전, 호환 조건과 변경 영향을 먼저 확인합니다. 정확히 검증된 Node는 공개 README의 macOS 26.5.1이며 npm/Git의 검증 버전은 기록되지 않았습니다.
별도 사용자 폴더는 경로를 별도 관리하고, 로컬은 프로젝트 의존성을 변경하며, 전역은 공유 설치에 영향을 줍니다. 아래 예제는 가이드 기준+별도 폴더를 사람이 선택했을 때만 사용합니다. 다른 조합은 AI용 원문의 해당 명령을 선택하세요.
선택한 실습 폴더의 터미널. 모든 placeholder를 실제 값으로 바꾸고 결과를 읽은 뒤 진행하세요.
# macOS only. Confirm engines/platform/license and both human choices first. BRIDGE_APPROVED_VERSION="<HUMAN_APPROVED_BRIDGE_VERSION>" BRIDGE_VERSION="0.1.0-alpha.1" && test "$BRIDGE_VERSION" = "$BRIDGE_APPROVED_VERSION" && npm install --prefix "$HOME/holmes-tools/agent-bridge/$BRIDGE_VERSION" --save-exact "@holmes-lab/agent-bridge@$BRIDGE_VERSION" && BRIDGE_CLI="$HOME/holmes-tools/agent-bridge/$BRIDGE_VERSION/node_modules/@holmes-lab/agent-bridge/dist/cli.js" && test -f "$BRIDGE_CLI" && BRIDGE_ACTUAL_VERSION="$(node "$BRIDGE_CLI" --version)" && test "$BRIDGE_ACTUAL_VERSION" = "$BRIDGE_VERSION" && node "$BRIDGE_CLI" --help
새 실습 공간과 private runtime 준비
기존 프로젝트 대신 새 실습 폴더 두 개를 사용하세요. 모든 경로는 실제 canonical 절대경로로 대체하고 credential 파일은 세션마다 다른 private 경로를 정합니다. 아래 초기화는 설정을 쓰므로 범위와 승인을 먼저 확인하세요. credential 내용을 복사하거나 웹에 붙여넣지 않습니다.
선택한 실습 폴더의 터미널. 모든 placeholder를 실제 값으로 바꾸고 결과를 읽은 뒤 진행하세요.
RUNTIME="<NEW_PRIVATE_ABSOLUTE_RUNTIME>" CLAUDE_WS="<CANONICAL_ABSOLUTE_WORKSPACE_A>" CODEX_WS="<CANONICAL_ABSOLUTE_WORKSPACE_B>" CLAUDE_CREDENTIAL="<NEW_PRIVATE_ABSOLUTE_FILE_A>" CODEX_CREDENTIAL="<NEW_PRIVATE_ABSOLUTE_FILE_B>" node "$BRIDGE_CLI" init --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" allow-workspace --path "$CLAUDE_WS" --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" allow-workspace --path "$CODEX_WS" --runtime-dir "$RUNTIME"
Claude 세션을 명시적으로 등록
운영자가 새 Claude 세션에 사용할 SESSION_UUID를 정하고 아래 변수를 실제 값으로 정의합니다. 먼저 등록하고 설정 미리보기를 확인한 뒤 적용합니다. install-claude가 출력하는 시작 명령을 사람이 검토해 실행합니다. Claude Channels의 development-channel 확인은 사람이 직접 결정하며 자동 신뢰하지 않습니다.
선택한 실습 폴더의 터미널. 모든 placeholder를 실제 값으로 바꾸고 결과를 읽은 뒤 진행하세요.
CLAUDE_SESSION_UUID="<UUID_FOR_THE_CLAUDE_SESSION_YOU_WILL_LAUNCH>" node "$BRIDGE_CLI" enroll --engine claude --native-session "$CLAUDE_SESSION_UUID" --workspace "$CLAUDE_WS" --display-name claude-a --transport claude-channel --credential-out "$CLAUDE_CREDENTIAL" --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" install-claude --workspace "$CLAUDE_WS" --credential-file "$CLAUDE_CREDENTIAL" --dry-run --runtime-dir "$RUNTIME" # Apply only after reviewing the preview; then inspect the printed launch command. node "$BRIDGE_CLI" install-claude --workspace "$CLAUDE_WS" --credential-file "$CLAUDE_CREDENTIAL" --runtime-dir "$RUNTIME"
Codex 설정 후 실제 thread 등록
daemon 조회의 socketPath를 CODEX_SOCKET에 넣습니다. daemon이 없으면 시작은 별도 운영 변경입니다. socket과 부모 폴더의 소유권·권한 요구를 준수하고 chmod로 무조건 우회하지 않습니다. 설정 후 출력된 명령으로 Codex를 열고 /new·/mcp를 확인한 다음 실제 thread ID를 등록합니다.
선택한 실습 폴더의 터미널. 모든 placeholder를 실제 값으로 바꾸고 결과를 읽은 뒤 진행하세요.
codex app-server daemon version CODEX_SOCKET="<ACTUAL_SOCKET_PATH_FROM_DAEMON>" node "$BRIDGE_CLI" install-codex --workspace "$CODEX_WS" --credential-file "$CODEX_CREDENTIAL" --codex-socket "$CODEX_SOCKET" --dry-run --runtime-dir "$RUNTIME" # Review, apply, launch the printed Codex command, then /new and /mcp. node "$BRIDGE_CLI" install-codex --workspace "$CODEX_WS" --credential-file "$CODEX_CREDENTIAL" --codex-socket "$CODEX_SOCKET" --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" codex-threads --codex-socket "$CODEX_SOCKET" --runtime-dir "$RUNTIME" THREAD_ID="<ACTUAL_NEW_CODEX_THREAD_ID>" node "$BRIDGE_CLI" enroll --engine codex --native-session "$THREAD_ID" --workspace "$CODEX_WS" --display-name codex-a --transport codex-app-server --credential-out "$CODEX_CREDENTIAL" --runtime-dir "$RUNTIME"
두 방향 route와 제한된 첫 왕복
runtime은 paused로 시작합니다. 필요한 두 방향만 허용하고 broker는 전용 터미널에서 실행합니다. 다른 터미널에서도 같은 RUNTIME과 BRIDGE_CLI를 정의한 뒤 resume합니다. 모델 사용 여부·입력 1회·시간·비용·종료 조건은 사람이 먼저 결정합니다. 사이트는 세션이나 모델을 실행하지 않습니다.
- 전송 수락
- 수신 측 bridge_ack
- 별도의 작업 완료 확인
선택한 실습 폴더의 터미널. 모든 placeholder를 실제 값으로 바꾸고 결과를 읽은 뒤 진행하세요.
node "$BRIDGE_CLI" allow-route --from "$CLAUDE_WS" --to "$CODEX_WS" --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" allow-route --from "$CODEX_WS" --to "$CLAUDE_WS" --runtime-dir "$RUNTIME" # Dedicated foreground terminal: node "$BRIDGE_CLI" run --codex-socket "$CODEX_SOCKET" --runtime-dir "$RUNTIME" # Another terminal with the same selected runtime: node "$BRIDGE_CLI" resume --reason "bounded pair ready" --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" status --runtime-dir "$RUNTIME"
실제 확인과 종료
송신 에이전트에게 bridge_peers에서 실제 peer를 확인한 뒤 실행 지시가 없는 짧은 인사 1개만 bridge_send로 보내도록 요청합니다. 수신 측은 bridge_inbox로 실제 내용을 읽고 bridge_ack로 확인합니다. ack는 작업 완료가 아니며 bridge_work_receipt는 별도 기록입니다. 응답 메시지도 필요하면 승인한 1회 왕복 범위 안에서 보냅니다. /mcp 표시만으로 전달 성공이라 하지 않습니다.
delivery_unknown은 자동 재전송하지 않습니다. 수신 측 관찰 후 공식 reconcile 절차를 검토합니다. confirmed_not_sent는 재전송을 유발할 수 있으므로 판단 없이 선택하지 않습니다. 마지막으로 pause·stop하고 필요하면 실습 등록 ID를 revoke합니다.
선택한 실습 폴더의 터미널. 모든 placeholder를 실제 값으로 바꾸고 결과를 읽은 뒤 진행하세요.
node "$BRIDGE_CLI" messages --state delivery_unknown --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" pause --reason "practice complete" --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" stop --runtime-dir "$RUNTIME" # Optional, after inspecting actual practice registration IDs: # node "$BRIDGE_CLI" revoke --registration "<ACTUAL_ID>" --reason "practice complete" --runtime-dir "$RUNTIME"