# Agent Mux

> Route tasks between Claude Code and Codex CLI — Subscription Efficiency Maximizer for AI coding subscriptions ($40-$400/mo)

- **Type:** MCP server
- **Install:** `agentstack add mcp-wowoyong-agent-mux`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [wowoyong](https://agentstack.voostack.com/s/wowoyong)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wowoyong](https://github.com/wowoyong)
- **Source:** https://github.com/wowoyong/agent-mux
- **Website:** https://www.npmjs.com/package/agent-mux-mcp

## Install

```sh
agentstack add mcp-wowoyong-agent-mux
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 (권장)

```bash
npm install -g agent-mux-mcp
mux setup
```

### 방법 2: Claude Code 플러그인

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

---

## 30초 Quick Start

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

```bash
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 안에서 일반 텍스트를 입력하면 자동으로 라우팅 + 실행되고, 매 실행 후 예산 바가 업데이트됩니다.

### 원샷 모드

```bash
# 자동 라우팅
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" 커맨드

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-wowoyong-agent-mux
- Seller: https://agentstack.voostack.com/s/wowoyong
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.