npm package: @kimyw/claude-codex-bridge
Description: Claude Code와 OpenAI Codex CLI를 서로 일반 `stdio` MCP 서버로 연결하는 로컬 브릿지입니다.
Latest version: 0.5.0

# 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 자동응답](#sampling-자동응답) | tmux 없이도 MCP sampling으로 상대 메시지에 자동 응답 |
| [Wake Method](#wake-method) | mux_send_keys, http_post, none 3종 wake-up 방식 |
| [Broker 병렬 세션](#broker-병렬-세션) | 같은 리포에서 slot별로 독립 대화 세션 운영 |
| [대용량 메시지 자동 분리](#대용량-메시지-자동-분리) | 10,000자 초과 메시지를 attachment 파일로 분리 |
| [tmux/psmux 연동](#tmuxpsmux-연동) | 터미널 멀티플렉서로 세션 자동 생성 및 wake-up |
| [상태 진단](#상태-진단) | ccb health로 전체 브릿지 상태 한눈에 확인 |
| [Broker 관리](#broker-관리) | ccb broker로 런타임 시작/중지/상태조회/상세검사 |
| [StatusLine HUD](#statusline-hud) | Claude Code 하단에 5h/7d 사용량 + 컨텍스트 사용량 표시 |

## 설치

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

또는

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

### 요구 사항

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

## 빠른 시작

```bash
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 전용 기능입니다.

**시작하기:**

```bash
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
```

**토론 템플릿:**

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

```bash
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, 기술 타당성, 개발 비용, 장기 유지보수 |

**토론 모니터링:**

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

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

---

### Broker 병렬 세션

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

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

별도 터미널에서:

```bash
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)를 사용해 자동으로 세션을 생성합니다.

```bash
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│
└─────────────────────────────┘
```

세션에 연결하려면:

```bash
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 주소만 허용하며, 외부 주소는 자동 거부됩니다.

---

### 상태 진단

```bash
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를 직접 관리하는 운영 명령입니다.

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

**inspect 옵션:**

```bash
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 터미널 하단에 사용량 정보를 실시간으로 표시합니다.

```bash
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` 대신 수동으로 두 터미널에서 각각 실행

## 개발

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

## License

MIT