Claude Code와 Codex CLI를 자동으로 오케스트레이션하는 AI 코딩 멀티플렉서
English | 한국어
Claude Code와 Codex CLI 구독을 동시에 사용하고 있다면, 하나가 rate limit에 걸릴 때 나머지 하나는 놀고 있습니다.
agent-mux는 이 유휴 시간을 제거합니다. 작업을 분석해서 최적의 CLI로 자동 라우팅하고, rate limit에 걸리면 다른 쪽으로 전환합니다.
$40/월(Pro+Plus)로 6시간 코딩 세션. agent-mux 없이는 90분이 한계.
| agent-mux 없이 | agent-mux 사용 | |
|---|---|---|
| 사용 가능 시간 | ~1.5시간 | ~6시간 |
| 처리 태스크 | ~15건 | ~49건 |
| 비용/태스크 | $1.33 | $0.82 |
npm install -g agent-mux-mcp
mux setupclaude plugin marketplace add wowoyong/agent-mux
claude plugin install agent-mux# 1. 설치
npm install -g agent-mux-mcp
# 2. 설정 — Claude 구독 선택, Codex 구독 선택, 자동 티어 감지
mux setup
# 3. 대화형 모드 — REPL 진입, 작업 입력하면 자동 라우팅
mux
# 4. 원샷 모드
mux "write unit tests for auth module"
# → [agent-mux] Routing → CODEX (test writing, confidence: 92%)
# → Codex working... ✓ Complete — 3 files (34s)mux인자 없이 mux를 실행하면 REPL에 진입합니다.
⚡ agent-mux v0.4.0 | standard tier ($120/mo)
Claude ████████████░░░░░░░░ 12/225 | Codex ██░░░░░░░░░░░░░░░░░░ 3/200
Type a task to route, or a command:
/status — budget dashboard
/go — auto-execute mode
/config — show configuration
/help — show help
/quit — exit
mux> write tests for auth module ← 자동 라우팅
mux> /go JWT 인증 시스템 구축 ← 자동 분해 + 실행
mux> /status ← 예산 대시보드
mux> /config ← 설정 확인
mux> /quit ← 종료
REPL 안에서 일반 텍스트를 입력하면 자동으로 라우팅 + 실행되고, 매 실행 후 예산 바가 업데이트됩니다.
# 자동 라우팅
mux "write unit tests for auth module"
# 라우팅 미리보기 (실행 안 함)
mux --dry-run "refactor the database module"
# 시그널 상세 분석
mux --verbose "fix the login bug"
# 강제 라우팅
mux --route=codex "generate API docs"
mux --route=claude "security audit"
# 예산 확인
mux status
# 설정
mux setup # 초기 설정 마법사
mux config # 현재 설정 JSON 출력mux go "사용자 대시보드 구축 — 차트, 테이블, API 연동"⚡ mux go — auto-routing + auto-execution
Decomposed into 4 subtasks (fan-out):
◆ [1] API 엔드포인트 설계 → CLAUDE
◆ [2] 차트 컴포넌트 구현 → CODEX
◆ [3] 테이블 컴포넌트 구현 → CODEX
◆ [4] API 연동 코드 작성 → CODEX
Phase 1: Claude tasks
◆ API 엔드포인트 설계
Claude:
...
Phase 2: Codex tasks
◆ 차트 컴포넌트 구현... (42s, 2 files)
◆ 테이블 컴포넌트 구현... (38s, 2 files)
◆ API 연동 코드 작성... (25s, 1 files)
═══ Complete ═══
Budget: Claude 13/225 | Codex 6/200
mux go는 다음을 수행합니다:
- 자동 분해 — 복잡한 작업을 독립적인 서브태스크로 분리 (번호 리스트, 불릿, "and"/"그리고" 기반 분할)
- 라우팅 결정 — 각 서브태스크에 Claude(설계/분석) 또는 Codex(구현/테스트) 지정
- 순차 실행 — Claude 태스크 먼저 실행한 후 Codex 태스크 실행
- 자동 머지 — Codex 결과를 git worktree에서 자동으로 merge (확인 프롬프트 없음)
- 에스컬레이션 — Codex 실패 시 자동으로 Claude에 에스컬레이션
분해가 불필요한 단순 작업은 단일 에이전트로 직접 실행됩니다.
agent-mux는 2-Phase 라우팅 엔진을 사용합니다. Budget 티어에서 100% 로컬 실행으로 라우팅에 LLM 토큰을 소비하지 않습니다.
우선순위 기반으로 조건에 해당하면 즉시 라우팅합니다.
| 우선순위 | 조건 | 라우팅 | 근거 |
|---|---|---|---|
| 1 | MCP 도구 필요 | Claude | MCP 접근은 Claude만 가능 |
| 2 | 대화형 상호작용 | Claude | 세션 내 대화가 필요 |
| 3 | 대화 컨텍스트 참조 | Claude | 이전 맥락은 Claude에만 존재 |
| 4 | 독립적 보안 감사 | Codex | 체계적 감사에 효율적 |
| 5 | 다수 파일 리팩토링 (>5) | Claude | 파일 간 조율이 필요 |
| 6 | 프로젝트 스캐폴딩 | Claude | 전체 아키텍처 이해 필요 |
Phase 1에서 매칭되지 않으면 20개 시그널의 가중치 점수를 계산합니다.
score = sum(signal_weight x signal_value) + sum(interaction_modifier)
score > 0 → Codex
score < 0 → Claude
score == 0 → budget_tiebreaker()
Codex 방향 시그널 (양수): 테스트 작성(+40), 자체 완결 태스크(+35), 보안 감사(+30), 문서 생성(+30), 코드 리뷰(+25), 리팩토링(+20), 디버깅(+15), 터미널 태스크(+10)
Claude 방향 시그널 (음수): MCP 필요(-100), 대화 컨텍스트(-100), 대화형(-100), 스캐폴딩(-100), 아키텍처 설계(-40), 다중 파일 조율(-35), 프로젝트 컨텍스트(-30), 프론트엔드(-20)
인터랙션 모디파이어:
- 프로젝트 컨텍스트가 필요한 리팩토링 → Claude 쪽으로 -40
- 자체 완결 + 검증 가능한 디버깅 → Codex 쪽으로 +30
- 다중 파일 테스트 작성 → Claude 쪽으로 -20
- 보안 리뷰 + 코드 리뷰 → Codex 쪽으로 +20
- 복잡 + 긴급 → Claude 쪽으로 -25
Claude 예산이 20% 이하로 떨어지면 Codex 쪽으로 +50점 보정, Codex가 20% 이하면 Claude 쪽으로 -50점 보정합니다.
사용자가 수동으로 라우팅을 변경하면 이를 학습하여 이후 유사 작업에 자동 적용합니다 (30초 캐시 TTL).
mux "유닛 테스트 작성해줘"
→ [agent-mux] Routing → CODEX (test writing, confidence: 92%)
mux "결제 시스템 아키텍처 설계해줘"
→ [agent-mux] Routing → CLAUDE (architectural design, confidence: 95%)
mux "이 JWT 에러 디버깅해줘"
→ [agent-mux] Routing → CLAUDE (debugging, context needed, confidence: 78%)
mux "JSDoc 추가해줘"
→ [agent-mux] Routing → CODEX (doc generation, confidence: 88%)
| Tier | Claude | Codex | 월 비용 | 라우팅 비율 | 엔진 | 바이어스 | 핵심 가치 |
|---|---|---|---|---|---|---|---|
| Budget | Pro $20 | Plus $20 | $40 | 30:70 | local | codex | 4x 코딩 시간 |
| Standard | Max 5x $100 | Plus $20 | $120 | 55:45 | local | balanced | 병렬 워크플로우 |
| Premium | Max 20x $200 | Plus $20 | $220 | 70:30 | hybrid (planned) | claude | 핸즈프리 라우팅 |
| Power | Max 20x $200 | Pro $200 | $400 | 65:35 | hybrid (planned) | adaptive | 최대 병렬성 |
| Tier | Claude (5시간당) | Codex (일일) | 동시 실행 |
|---|---|---|---|
| Budget | 45 | 200 | 1 |
| Standard | 225 | 200 | 1 |
| Premium | 900 | 200 | 1 |
| Power | 900 | 무제한 | 3 |
| Tier | 전략 | 최대 재시도 |
|---|---|---|
| Budget | fix (패치만 시도) | 1 |
| Standard | fix_then_redo (패치 → 재실행) | 2 |
| Premium | fix_then_redo | 2 |
| Power | full (패치 → 재실행 → Claude 완전 위임) | 3 |
| Feature | Budget $40 | Standard $120 | Premium $220 | Power $400 |
|---|---|---|---|---|
| Local routing engine | O | O | O | O |
| LLM-assisted routing (planned) | - | 선택 | 상시 | 상시 |
| 전체 CLI 명령어 | O | O | O | O |
| Override flags | O | O | O | O |
| Batch mode (planned) | 30s | 15s | 5s | 3s |
| Parallel dispatch | - | O | O | O |
| Auto-escalation | 1회 | 2회 | 2회 | 3회 |
Task decomposition (mux go) |
O | O | O | O |
| Concurrent Codex | 1 | 1 | 1 | 3 |
| Conservation mode (planned) | ON | - | - | - |
| 플래그 | 기본값 | 설명 |
|---|---|---|
--dry-run |
OFF | 라우팅 결정만 표시, 실행 안 함 |
--verbose |
OFF | 활성 시그널 상세 분석 표시 |
--route=claude|codex |
auto | 강제 라우팅 (confidence 100%) |
--auto-apply |
OFF | Codex 결과 확인 없이 자동 적용 |
--confirm |
ON (Codex) | Codex 결과 diff 확인 후 적용 |
Codex 작업은 안전하게 격리 실행됩니다.
PREPARE → SPAWN → MONITOR → VALIDATE → INTEGRATE
- PREPARE — Git worktree 생성, 메인 작업 디렉토리와 완전 분리
- SPAWN —
codex exec --full-auto --json --ephemeral로 실행 - MONITOR — JSONL event stream 실시간 파싱, 90초 stall 감지 (타임아웃: 420초)
- VALIDATE — 4-Stage 검증
- Stage 1: 파일 범위 검사 (deny-list 위반 체크)
- Stage 2: 테스트/린트 실행
- Stage 3: Claude 리뷰
- Stage 4: 사용자 확인 (
--auto-apply시 스킵)
- INTEGRATE — 승인 시
git merge --no-ff로 merge, 거부 시 worktree 삭제 + 브랜치 롤백
Codex 결과는 컬러 diff로 미리보기됩니다 (최대 50줄 프리뷰, d 입력 시 전체 diff 표시). 사용자는 y(적용), n(폐기), d(전체 diff) 중 선택할 수 있습니다.
다음 파일은 Codex가 수정할 수 없습니다 (자동 차단):
.github/workflows/* .env* *.pem *.key
*.p12 *.jks package.json package-lock.json
yarn.lock pnpm-lock.yaml Gemfile.lock poetry.lock
go.sum Cargo.lock Dockerfile docker-compose*.yml
Makefile .npmrc .pypirc Jenkinsfile
커스텀 패턴은 설정 파일의 deny_list에 추가할 수 있습니다.
Codex가 실패하면 설정된 전략에 따라 자동 재시도하고, 최대 재시도 횟수 초과 시 Claude에 에스컬레이션합니다. 에스컬레이션 시 실패 원인이 Claude에 전달됩니다.
mux status=== agent-mux Status ===
Tier: standard ($120/mo)
Codex CLI: [ok] v0.112.0
Claude: ############-------- 54/225
Codex: ######-------------- 12/200
Routing: local | Bias: balanced | Split: 55/45
설정 파일의 budget.warnings 배열로 경고 임계값을 지정합니다 (기본: 50%, 75%, 90%).
- 50%: 정보 알림
- 75%: 경고 — 라우팅 바이어스 자동 조정
- 90%: 위험 — 소진된 에이전트 회피 모드
| 상황 | 기본 동작 |
|---|---|
| Claude 소진 | codex_only — Codex만 사용 |
| 양쪽 소진 | queue_and_wait — 대기열에 저장 |
mux setup대화형 위저드가 Claude 구독과 Codex 구독을 선택받고, 자동으로 티어를 결정하여 .agent-mux/config.yaml에 저장합니다.
=== agent-mux Setup ===
Codex CLI: [ok] v0.112.0
Claude plan:
1) Pro ($20/mo) -- ~45 messages/5hr
2) Max 5x ($100/mo) -- ~225 messages/5hr
3) Max 20x ($200/mo) -- ~900 messages/5hr
Select (1-3): 2
Codex plan:
1) Plus ($20/mo) -- 1 concurrent task
2) Pro ($200/mo) -- 3 concurrent tasks
Select (1-2): 1
Tier: standard ($120/mo)
Routing: local | 55% Claude / 45% Codex
Config saved to .agent-mux/config.yaml
설정 파일 위치: .agent-mux/config.yaml (프로젝트) 또는 ~/.agent-mux/config.yaml (글로벌)
# .mux-config.yaml (Budget 티어 기본값)
schema_version: 1
tier: budget # budget | standard | premium | power
claude:
plan: pro # pro | max_5x | max_20x
cost: 20
codex:
plan: plus # plus | pro
cost: 20
mode: local # local | cloud_and_local
routing:
engine: local # local | hybrid
bias: codex # codex | balanced | claude | adaptive
split:
claude: 30
codex: 70
escalation:
enabled: true
strategy: fix # fix | fix_then_redo | full
max_retries: 1
# batch_mode: (planned)
# enabled: true
# queue_timeout_sec: 30
# conservation: (planned)
# enabled: true
# codex_first_on_uncertain: true
budget:
warnings: [50, 75, 90]
# degradation: (planned)
# on_claude_exhausted: codex_only
# on_both_exhausted: queue_and_wait
# Optional: 커스텀 deny-list 패턴 (기본값에 추가됨)
# deny_list:
# - "*.secret"
# - "internal/**"독립 CLI 외에 Claude Code 플러그인으로도 사용할 수 있습니다:
claude plugin marketplace add wowoyong/agent-mux
claude plugin install agent-mux
# Claude Code 재시작 후
/mux "write tests"
/mux-setup
/mux-status| 플러그인 명령어 | 설명 |
|---|---|
/mux "작업" |
작업 라우팅 및 실행 |
/mux-status |
예산 및 작업 현황 |
/mux-config |
설정 조회/변경 |
/mux-setup |
초기 설정 마법사 |
| 명령어 | 설명 |
|---|---|
mux |
REPL 대화형 모드 진입 |
mux "<작업>" |
자동 라우팅 + 실행 |
mux go "<작업>" |
자동 분해 + 라우팅 + 실행 |
mux status |
예산 및 상태 대시보드 |
mux setup |
초기 설정 마법사 |
mux config |
현재 설정 JSON 출력 |
agent-mux는 단독으로 완벽히 동작합니다. 다음 플러그인들과 함께 사용하면 더욱 강력합니다:
- harness-planner — 복잡한 작업을 자동 분해하여 mux-ready 서브태스크로 변환
- architecture-enforcer — Codex 스폰 시 아키텍처 규칙을 자동 주입하여 일관성 보장
- harness-docs — AGENTS.md 기반 프로젝트 컨텍스트로 라우팅 정확도 향상
이 플러그인들은 세션 시작 시 자동으로 감지되며, 감지 실패 시에도 agent-mux 핵심 기능에 영향을 주지 않습니다.
agent-mux는 두 개의 독립 컴포넌트로 구성됩니다:
| 컴포넌트 | 형태 | 역할 |
|---|---|---|
| Claude Code Plugin | Markdown (skills, commands, agents, hooks) | 사용자 인터페이스, 라우팅 판단, 결과 리뷰 |
MCP Server (agent-mux-mcp) |
TypeScript | Codex 프로세스 생성, 예산 추적, 상태 관리 |
User → mux "task"
│
Task Router (local, 0 tokens)
├─ Phase 1: Hard Rules
└─ Phase 2: Weighted Scoring
│
┌─────┴──────┐
│ │
Route: Claude Route: Codex
(claude --print) │
spawn_codex (full-auto)
in git worktree
│
┌────┴────┐
│ │
Success Failure
├ Diff └ Retry / Escalate
├ Confirm → Claude fallback
└ Merge
- TypeScript — 전체 코어 + MCP 서버
- MCP (Model Context Protocol) — Claude Code 플러그인 통합
- Commander.js — CLI 프레임워크
- Chalk + Ora — 터미널 UI (컬러 출력, 스피너)
- Vitest — 유닛 테스트
OpenAI Harness Engineering과 oh-my-openagent에서 영감을 받았습니다.
- "Humans steer, agents execute" — 개발자는 방향을 정하고, agent가 실행한다
- Zero-overhead routing — Budget 티어에서 라우팅에 0 토큰 소비. 키워드 매칭만으로 20개 시그널 추출
- Repository as source of truth — 모든 Codex 작업은 git worktree로 격리, merge 또는 rollback으로 깔끔한 이력 유지
- Subscription Efficiency Maximizer — 구독 비용 대비 최대 생산성. Rate limit의 유휴 시간을 제거
Issues와 PRs를 환영합니다!