Agent Mux

agent-mux

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

[](https://www.npmjs.com/package/agent-mux-mcp) [](LICENSE) [](https://github.com/wowoyong/agent-mux/actions)

[English](./README.en.md) | 한국어

---

왜 agent-mux인가?

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 |

---

설치

방법 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 (즉시 결정)

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

| 우선순위 | 조건 | 라우팅 | 근거 | |:---:|------|--------|------| | 1 | MCP 도구 필요 | Claude | MCP 접근은 Claude만 가능 | | 2 | 대화형 상호작용 | Claude | 세션 내 대화가 필요 | | 3 | 대화 컨텍스트 참조 | Claude | 이전 맥락은 Claude에만 존재 | | 4 | 독립적 보안 감사 | Codex | 체계적 감사에 효율적 | | 5 | 다수 파일 리팩토링 (>5) | Claude | 파일 간 조율이 필요 | | 6 | 프로젝트 스캐폴딩 | Claude | 전체 아키텍처 이해 필요 |

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

Phase 1에서 매칭되지 않으면 20개 시그널의 가중치 점수를 계산합니다.

score = sum(signal_weight x signal_value) + sum(interaction_modifier)

score > 0  → Codex
score "` | 자동 라우팅 + 실행 |
| `mux go ""` | 자동 분해 + 라우팅 + 실행 |
| `mux status` | 예산 및 상태 대시보드 |
| `mux setup` | 초기 설정 마법사 |
| `mux config` | 현재 설정 JSON 출력 |

---

## Works Great With

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

- **[harness-planner](https://github.com/wowoyong/claude-plugin-harness-planner)** — 복잡한 작업을 자동 분해하여 mux-ready 서브태스크로 변환
- **[architecture-enforcer](https://github.com/wowoyong/claude-plugin-architecture-enforcer)** — Codex 스폰 시 아키텍처 규칙을 자동 주입하여 일관성 보장
- **[harness-docs](https://github.com/wowoyong/claude-plugin-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](https://openai.com)과 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](LICENSE)

---

## 기여

Issues와 PRs를 환영합니다!

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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [wowoyong](https://github.com/wowoyong)
- **Source:** [wowoyong/agent-mux](https://github.com/wowoyong/agent-mux)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/agent-mux-mcp

Install and usage instructions live in the source repository linked above.