agent-mux

Claude Code와 Codex CLI를 자동으로 오케스트레이션하는 AI 코딩 멀티플렉서

English | 한국어

왜 agent-mux인가?

Claude Code와 Codex CLI 구독을 동시에 사용하고 있다면, 하나가 rate limit에 걸릴 때 나머지 하나는 놀고 있습니다.

agent-mux는 이 유휴 시간을 제거합니다. 작업을 분석해서 최적의 CLI로 자동 라우팅하고, rate limit에 걸리면 다른 쪽으로 전환합니다.

$40/월(Pro+Plus)로 6시간 코딩 세션. agent-mux 없이는 90분이 한계.

설치

방법 1: 독립 CLI (권장)

npm install -g agent-mux-mcp
mux setup

방법 2: Claude Code 플러그인

claude plugin marketplace add wowoyong/agent-mux
claude plugin install agent-mux

30초 Quick Start

# 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)

사용 방법

대화형 모드 (REPL)

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 — "Just Do It" 커맨드

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는 다음을 수행합니다:

1. 자동 분해 — 복잡한 작업을 독립적인 서브태스크로 분리 (번호 리스트, 불릿, "and"/"그리고" 기반 분할)
2. 라우팅 결정 — 각 서브태스크에 Claude(설계/분석) 또는 Codex(구현/테스트) 지정
3. 순차 실행 — Claude 태스크 먼저 실행한 후 Codex 태스크 실행
4. 자동 머지 — Codex 결과를 git worktree에서 자동으로 merge (확인 프롬프트 없음)
5. 에스컬레이션 — Codex 실패 시 자동으로 Claude에 에스컬레이션

분해가 불필요한 단순 작업은 단일 에이전트로 직접 실행됩니다.

라우팅 동작 원리

agent-mux는 2-Phase 라우팅 엔진을 사용합니다. Budget 티어에서 100% 로컬 실행으로 라우팅에 LLM 토큰을 소비하지 않습니다.

Phase 1: Hard Rules (즉시 결정)

우선순위 기반으로 조건에 해당하면 즉시 라우팅합니다.

Phase 2: 가중치 기반 시그널 점수

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%)

지원 티어

티어별 Rate Limit

에스컬레이션 전략

기능 매트릭스

플래그 레퍼런스

Codex 실행 파이프라인

Codex 작업은 안전하게 격리 실행됩니다.

PREPARE → SPAWN → MONITOR → VALIDATE → INTEGRATE

1. PREPARE — Git worktree 생성, 메인 작업 디렉토리와 완전 분리
2. SPAWN — codex exec --full-auto --json --ephemeral로 실행
3. MONITOR — JSONL event stream 실시간 파싱, 90초 stall 감지 (타임아웃: 420초)
4. VALIDATE — 4-Stage 검증
   • Stage 1: 파일 범위 검사 (deny-list 위반 체크)
   • Stage 2: 테스트/린트 실행
   • Stage 3: Claude 리뷰
   • Stage 4: 사용자 확인 (--auto-apply 시 스킵)
5. INTEGRATE — 승인 시 git merge --no-ff로 merge, 거부 시 worktree 삭제 + 브랜치 롤백

Diff 미리보기

Codex 결과는 컬러 diff로 미리보기됩니다 (최대 50줄 프리뷰, d 입력 시 전체 diff 표시). 사용자는 y(적용), n(폐기), d(전체 diff) 중 선택할 수 있습니다.

파일 보호 (Deny-list)

다음 파일은 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%: 위험 — 소진된 에이전트 회피 모드

소진 대응

설정

설정 마법사

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/**"

Claude Code 플러그인 모드

독립 CLI 외에 Claude Code 플러그인으로도 사용할 수 있습니다:

claude plugin marketplace add wowoyong/agent-mux
claude plugin install agent-mux
# Claude Code 재시작 후
/mux "write tests"
/mux-setup
/mux-status

CLI 명령어 요약

Works Great With

agent-mux는 단독으로 완벽히 동작합니다. 다음 플러그인들과 함께 사용하면 더욱 강력합니다:

• harness-planner — 복잡한 작업을 자동 분해하여 mux-ready 서브태스크로 변환
• architecture-enforcer — Codex 스폰 시 아키텍처 규칙을 자동 주입하여 일관성 보장
• harness-docs — AGENTS.md 기반 프로젝트 컨텍스트로 라우팅 정확도 향상

이 플러그인들은 세션 시작 시 자동으로 감지되며, 감지 실패 시에도 agent-mux 핵심 기능에 영향을 주지 않습니다.

아키텍처

agent-mux는 두 개의 독립 컴포넌트로 구성됩니다:

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의 유휴 시간을 제거

라이선스

MIT

기여

Issues와 PRs를 환영합니다!

https://github.com/wowoyong/agent-mux/issues