Claude-Codex Bridge

Claude Code와 OpenAI Codex CLI를 서로 일반 stdio MCP 서버로 연결하는 로컬 브릿지입니다.

두 AI 에이전트가 같은 워크스페이스에서 서로 메시지를 주고받으며 협업할 수 있습니다.

기능 요약

| 기능 | 설명 | | --- | --- | | 양방향 메시징 | Claude와 Codex가 MCP 도구로 메시지를 주고받음 | | 대화 모드 | freeform, design, code-review, brainstorm, task-division, debate 6종 | | 자율 토론 | Claude와 Codex가 사람 개입 없이 다회차 토론 수행 | | Sampling 자동응답 | tmux 없이도 MCP sampling으로 상대 메시지에 자동 응답 | | Wake Method | mux_send_keys, http_post, none 3종 wake-up 방식 | | Broker 병렬 세션 | 같은 리포에서 slot별로 독립 대화 세션 운영 | | 대용량 메시지 자동 분리 | 10,000자 초과 메시지를 attachment 파일로 분리 | | tmux/psmux 연동 | 터미널 멀티플렉서로 세션 자동 생성 및 wake-up | | 상태 진단 | ccb health로 전체 브릿지 상태 한눈에 확인 | | Broker 관리 | ccb broker로 런타임 시작/중지/상태조회/상세검사 | | StatusLine HUD | Claude Code 하단에 5h/7d 사용량 + 컨텍스트 사용량 표시 |

설치

npm install -g @kimyw/claude-codex-bridge

또는

bun install -g @kimyw/claude-codex-bridge

요구 사항

• Bun (런타임)
• Node.js 18+
• Claude Code CLI (claude)
• OpenAI Codex CLI (codex)
• tmux 또는 psmux (권장, 없으면 수동 실행)

빠른 시작

cd ~/my-project
ccb init          # MCP 서버 등록 + 상태 디렉터리 생성
ccb start         # tmux 세션 생성 (pane 0: Claude, pane 1: Codex)

세션이 뜨면 Claude에게 "Codex에게 인사해봐"라고 말하면 됩니다. Claude가 reply 도구로 메시지를 보내고, Codex가 check_messages로 받아서 send_message로 응답합니다.

기능 상세

양방향 메시징

Claude와 Codex는 각각 MCP 서버를 통해 메시지를 주고받습니다.

Claude 쪽 도구:

| 도구 | 용도 | 예시 | | --- | --- | --- | | reply | Codex에게 메시지 전송 | reply({ text: "이 함수 리뷰 부탁해" }) | | check_messages | Codex에서 온 새 메시지 확인 | check_messages() 또는 check_messages({ max_messages: 10 }) | | set_mode | 대화 모드 전환 | set_mode({ mode: "code-review" }) | | reset_session | 세션 초기화 | reset_session({ confirm: true }) | | health_check | 서버 상태 조회 | health_check() |

Codex 쪽 도구:

| 도구 | 용도 | 예시 | | --- | --- | --- | | send_message | Claude에게 메시지 전송 | send_message({ text: "LGTM, 다만 에러 핸들링 추가 필요" }) | | check_messages | Claude에서 온 새 메시지 확인 | check_messages() | | get_history | 대화 이력 조회 | get_history({ limit: 50 }) 또는 get_history({ mode: "design" }) | | set_mode | 대화 모드 전환 | set_mode({ mode: "design" }) | | reset_session | 세션 초기화 | reset_session({ confirm: true }) | | health_check | 서버 상태 조회 | health_check() |

check_messages는 읽지 않은 메시지만 반환합니다. 메시지가 더 있으면 다시 호출하면 됩니다.

대화 모드

set_mode로 대화 구조를 전환하면 양쪽 에이전트에 구조화된 지시문이 자동으로 전달됩니다.

set_mode({ mode: "design" })

| 모드 | 구조 | 사용 시점 | | --- | --- | --- | | freeform | 자유 대화, 제약 없음 | 기본값. 일반적인 대화 | | design | PROPOSAL → AGREE/COUNTER-PROPOSAL → APPROVED | 설계 논의를 수렴시킬 때 | | code-review | CODE → VERDICT/FINDINGS/SUMMARY | 코드 리뷰 요청/수행 | | brainstorm | IDEATE → SYNTHESIZE → RANK 3단계 | 아이디어 발산 후 수렴 | | task-division | ANALYZE → ASSIGN → CONFIRM 3단계 | 작업을 Claude/Codex에 분배 | | debate | POSITION/REASONING/AGREEMENT/DEBATE_STATUS | 자율 토론 |

모드 전환은 메시지 없이도 감지됩니다. check_messages 응답에 mode_changed: true와 mode_instructions가 포함됩니다.

선택적으로 메타데이터를 함께 전달할 수 있습니다:

set_mode({ mode: "design", meta: { topic: "API 인증 구조", deadline: "이번 주" } })

자율 토론 모드

두 AI가 사람 개입 없이 주제에 대해 자동으로 왕복 토론합니다. broker backend 전용 기능입니다.

시작하기:

ccb init --backend broker
ccb start
ccb debate "이 아키텍처의 장단점을 분석해줘" --rounds 5

동작 흐름:

1. broker를 자동 기동
2. 대화 모드를 debate로 전환, 구조화된 상태(라운드, 발언자, 수렴 플래그) 설정
3. Claude에게 개시 메시지 주입
4. Claude와 Codex가 long-poll 기반으로 자동 왕복 토론 수행
5. 양측이 DEBATE_STATUS: converged를 보내면 task-division 모드로 자동 전환
6. max_rounds 초과 시 상태가 blocked로 전환되고 양측에 통지

각 AI의 응답 형식:

POSITION: 자신의 입장
REASONING: 근거
AGREEMENT: 상대방 의견에 동의하는 부분
OPEN_ISSUES: 미해결 쟁점
DEBATE_STATUS: continue | converged | blocked

토론 템플릿:

특정 유형의 토론에 최적화된 프리셋을 사용할 수 있습니다:

ccb debate "PR #42의 변경사항" --template code-review --rounds 3
ccb debate "마이크로서비스 vs 모놀리스" --template architecture
ccb debate "로그인 실패 버그" --template bug-analysis
ccb debate "다크모드 도입 여부" --template design-decision

| 템플릿 | 포커스 | | --- | --- | | code-review | 코드 품질, 유지보수성, 성능, 정확성 | | architecture | 확장성, 단순성, 운영비용, 미래 확장성 | | bug-analysis | 다중 가설, 증거 평가, 수정안 리스크 | | design-decision | UX, 기술 타당성, 개발 비용, 장기 유지보수 |

토론 모니터링:

ccb debate status            # 현재 라운드, 발언자, 수렴 상태 대시보드
ccb debate export --format md  # 마크다운 기록 출력 (파일 리다이렉션 가능)

ccb debate export > debate-log.md로 토론 기록을 파일로 저장할 수 있습니다.

Broker 병렬 세션

broker backend를 사용하면 같은 리포지토리에서 slot별로 독립적인 대화 세션을 운영할 수 있습니다.

ccb init --backend broker --slot review
ccb start review-ui --slot review

별도 터미널에서:

ccb init --backend broker --slot debug
ccb start debug-session --slot debug

이제 review slot과 debug slot은 완전히 독립된 대화를 진행합니다. 각 slot은 자체 conversation, mode, message history를 가집니다.

v1 vs broker:

| | v1 (기본) | broker | | --- | --- | --- | | 동시 세션 | 워크스페이스당 1개 | slot별 병렬 | | 프로세스 재시작 | 읽음 위치가 초기화될 수 있음 | 안정적으로 유지됨 | | 대화 초기화 | 파일 삭제 후 재시작 | 이전 대화를 archive로 보존 | | 자율 토론 (long-poll) | 미지원 | 지원 | | v1에서 전환 시 | — | 기존 v1 대화를 자동 import |

대용량 메시지 자동 분리

10,000자를 초과하는 메시지는 자동으로 별도 파일로 분리됩니다. 사용자가 설정할 것은 없습니다.

• 수신 측 AI는 attachment 파일을 읽은 뒤 응답하라는 지시를 자동으로 받음
• 정확히 10,000자까지는 inline, 초과분만 분리

tmux/psmux 연동

ccb start는 터미널 멀티플렉서(tmux 또는 psmux)를 사용해 자동으로 세션을 생성합니다.

ccb start                    # 기본 세션 이름 'bridge'
ccb start my-session         # 커스텀 세션 이름
ccb start --slot review      # broker slot 지정

생성되는 세션 구조:

┌─────────────────────────────┐
│ Pane 0: claude              │
│ --dangerously-skip-perms    │
├─────────────────────────────┤
│ Pane 1: codex               │
│ --sandbox danger-full-access│
└─────────────────────────────┘

세션에 연결하려면:

tmux attach -t bridge        # 또는 지정한 세션 이름

tmux/psmux가 없는 환경에서는 두 터미널을 수동으로 열고 각각 claude와 codex를 실행하면 됩니다.

Sampling 자동응답

broker backend에서 MCP 클라이언트가 sampling/createMessage를 지원하면, bridge 서버가 새 메시지를 감지할 때마다 상대 AI에게 직접 답변 생성을 요청합니다. tmux/psmux 없이도 완전 자동 왕복 대화가 가능합니다.

동작 흐름:

1. auto-reply loop가 broker inbox를 long-poll (20초 대기)
2. 새 메시지 도착 시 최근 대화 이력(12턴)과 함께 sampling 요청 생성
3. MCP 클라이언트가 LLM 응답을 생성하면 broker에 자동 enqueue
4. 상대측도 동일하게 동작하여 양방향 자동 왕복

특징:

• tmux/psmux wake-up 없이도 자동 응답 가능
• 모든 대화 모드(freeform, design, debate 등)에서 동작
• 클라이언트가 sampling을 지원하지 않으면 자동 비활성화, 기존 check_messages + wake-up fallback 사용
• 멀티 인스턴스 감지 시 충돌 방지를 위해 자동 일시정지

health_check 응답의 auto_reply_* 필드로 현재 자동응답 상태를 확인할 수 있습니다:

| 필드 | 설명 | | --- | --- | | auto_reply_enabled | 자동응답 활성화 여부 | | auto_reply_disabled_reason | 비활성화 사유 (sampling 미지원 등) | | auto_reply_last_reply_at | 마지막 자동응답 시각 (ISO 8601) | | auto_reply_last_error | 마지막 에러 메시지 |

Wake Method

상대 AI에게 새 메시지 도착을 알리는 방법입니다. broker가 peer 등록 시 자동으로 결정합니다.

| 방식 | 설명 | 조건 | | --- | --- | --- | | mux_send_keys | tmux/psmux 패인에 키 입력 전송 | tmux/psmux 세션 내에서 실행 중일 때 | | http_post | 로컬 HTTP POST로 알림 전송 | loopback(127.0.0.1/localhost) 주소만 허용 | | none | 알림 없음 (polling으로 동작) | 위 조건 모두 불충족 시 |

http_post는 보안을 위해 loopback 주소만 허용하며, 외부 주소는 자동 거부됩니다.

상태 진단

ccb health

설정, 세션, CLI 도구, broker 상태 등을 한번에 점검합니다.

출력 예시:

[ccb] Health Check

[OK] Backend: broker
[OK] .mcp.json found
[OK] Session: abc-123 (mode: freeform, turns: 5)
[OK] Terminal multiplexer: tmux
[OK] Claude CLI: /usr/local/bin/claude
[OK] Codex CLI: /usr/local/bin/codex
[OK] Bun: 1.3.5

[Broker]
[OK] Broker health: active_conversations=1 active_peers=2

[Auto-Reply]
[OK] Enabled (last reply: 2s ago)

Broker 관리

broker backend를 직접 관리하는 운영 명령입니다.

ccb broker start             # broker 미리 기동
ccb broker restart           # broker 재시작
ccb broker stop              # broker 종료
ccb broker status            # 런타임 + workspace 상태 요약
ccb broker inspect           # 상세 검사

inspect 옵션:

ccb broker inspect --slot review          # 특정 slot만
ccb broker inspect --include-archived     # 아카이브된 대화 포함
ccb broker inspect --show-messages        # 메시지 본문 출력
ccb broker inspect --message-limit 50     # 메시지 수 제한

ccb broker status로 현재 활성 slot, 대화 수, 연결된 AI 상태를 확인할 수 있습니다.

StatusLine HUD

Claude Code 터미널 하단에 사용량 정보를 실시간으로 표시합니다.

ccb statusline

설치 후 Claude Code를 재시작하면 하단에 다음과 같은 상태 표시줄이 나타납니다:

Opus | 5h: 23% | 7d: 41% | Ctx: 45% 450k/1000k

| 항목 | 설명 | | --- | --- | | 5h: 23% | 5시간 롤링 윈도우 사용량 | | 7d: 41% | 주간 한도 사용량 | | Ctx: 45% 450k/1000k | 컨텍스트 윈도우 사용량 (현재/최대) |

• 60% 이상: 노란색, 85% 이상: 빨간색
• 5h 사용량 80% 이상 시 리셋까지 남은 시간 표시
• Claude Code가 응답할 때마다 자동 업데이트

CLI 명령어 요약

| 명령어 | 설명 | | --- | --- | | ccb init [--force] [--backend v1\|broker] [--slot name] | 현재 프로젝트에 bridge 설정 | | ccb start [session-name] [--slot name] | tmux/psmux 세션 생성 | | ccb stop [--slot name] | 세션 종료 | | ccb restart [session-name] [--slot name] | 세션 재시작 | | ccb health | 전체 상태 점검 | | ccb broker start\|restart\|stop\|status\|inspect | broker 런타임 관리 | | ccb debate <topic> [--rounds N] [--template name] | 자율 토론 시작 | | ccb debate status | 토론 상태 확인 | | ccb debate export [--format md] | 토론 기록 출력 | | ccb statusline | Claude Code HUD 상태 표시줄 설치 |

알려진 한계

• v1 backend에서는 slot별 병렬 세션 미지원 (병렬이 필요하면 --backend broker 사용)
• debate 모드의 long-poll은 broker backend 전용
• 하나의 slot에 여러 MCP 인스턴스를 붙이면 메시지 중복 소비 위험
• tmux 없이 완전 자동응답을 하려면 MCP client가 sampling capability를 지원해야 함
• AI가 check_messages 호출을 따르지 않으면 토론이 멈출 수 있음 (수동으로 "check for messages" 지시 가능)
• tmux/psmux가 없으면 ccb start 대신 수동으로 두 터미널에서 각각 실행

개발

git clone https://github.com/kimyeongwoo/claude-codex-bridge.git
cd claude-codex-bridge
bun install
bun run test
bun run build

License

MIT