cmux-team

Multi-agent development orchestration with Claude Code + cmux.

日本語版 README はこちら

Demo

https://github.com/user-attachments/assets/1d402a69-f48c-4a43-b52d-9c80f0f90ea1

Why cmux-team?

Claude Code's built-in sub-agents are useful, but you can't see what they're doing. You only get the final result — the process is a black box.

This matters more than it might seem. When AI agents work invisibly, two problems compound:

• Late detection: You only discover something went wrong after the work is done — wasting compute and time, with no way to intervene mid-course
• No improvement signal: Without seeing intermediate behavior, you can't tell why a result was good or bad — which makes it hard to improve your prompts, tasks, and agent design

cmux-team is an AI observatory, not another automation black box. The terminal panes aren't decoration — they're the product. A 10-second glance at a Conductor pane is often enough to catch a problem that would otherwise only surface at the end.

To peek into another project's runtime state without leaving your shell: cmux-team status --project-root /path/to/other (read-only by default; cross-project writes require --project-root-confirm or CMUX_TEAM_PROJECT_ROOT_CONFIRM=1).

The design principle: reduce cognitive load by making the process visible, not by hiding it.

What you do: Give Claude instructions in natural language. What Claude does: Splits panes via cmux, launches sub-agents, monitors them, and integrates results — all in plain sight.

Prerequisites

• Claude Code installed
• cmux installed
• bun installed (required for the Manager daemon)
• Running Claude Code inside a cmux session
• Nerd Font (recommended) — enhances TUI dashboard icons
  hljs language-bash

  Copy

  brew install --cask font-hack-nerd-font
  

  Works without Nerd Font (falls back to Unicode symbols). Set CMUX_NERD_FONT=0 to use fallback icons explicitly.

Installation

npm install -g @hummer98/cmux-team

About auto-update

The daemon detects new versions via update-notifier and surfaces them in the TUI banner. Install is always manual — run npm i -g @hummer98/cmux-team@<latest> yourself to avoid surprises across mixed Node environments (Volta / nvm / Homebrew).

Two modes (default: off):

Configuration (precedence: env > config > default):

• CMUX_TEAM_AUTO_UPDATE=off|notify (also accepts 0|false as off)
• .team/config.json: { "autoUpdate": "off" | "notify" }

Related:

• NO_UPDATE_NOTIFIER=1 disables detection (standard update-notifier env var)
• Boot log: auto_update_config mode=<mode> source=<env|config|default>

Breaking change (v4.5.0, T294):

• The task mode (auto-creation of update tasks) is removed. CMUX_TEAM_AUTO_UPDATE=task|1|true and .team/config.json: autoUpdate: "task" | true | false now exit with status 1.
• The cmux-team self-update subcommand is removed.
• Migration: set autoUpdate to notify (or off), then run npm install -g @hummer98/cmux-team@latest when the banner appears.

Configuration (.team/config.json)

Created per-project by cmux-team start. All keys are optional — the file can be edited by hand and is re-read on next start. General precedence: CLI flag > env var > .team/config.json > built-in default.

Example:

{
  "mainBranch": "develop",
  "layout": "16x9",
  "sleepPrevention": "idle",
  "autoUpdate": "notify",
  "models": { "conductor": "claude-sonnet-4-6" }
}

See docs/spec/05-install-and-infrastructure.md for the full resolution semantics (including mainBranch auto-detection and worktree start-point order).

Usage

Basic Workflow

Start cmux, launch Claude Code inside it.

$ cmux-team start
  → Daemon starts with TUI dashboard
  → Manager / Master panes created, Conductors spawned
  → Switch to Master pane to give tasks

You:    Build a TODO app with React
Claude: Task created.
  → Daemon detects task → assigns to an idle Conductor
  → Conductor spawns Agents as tabs in the same pane
  → Watch each agent working in real time

You:    How's it going?
Claude: (checks manager.log, cmux tree)
        Conductor-1: implementing (2/3 agents done)

You:    Also clean up worktrees
Claude: → cmux-team create-task --title "..." --status ready
       → Daemon assigns it to another idle Conductor in parallel

Commands

CLI Commands (run from terminal)

See cmux-team --help for the full list. Common commands:

Lifecycle

Note: cmux-team stop was removed in v4.3.0. The daemon auto-stops when the cmux session exits (pidfile release). To terminate manually: kill <pid> (see .team/daemon.pid).

Task management

Base branch (--base-branch): By default each task's worktree is cut from your mainBranch (resolved via env CMUX_TEAM_MAIN_BRANCH → config.mainBranch → origin/HEAD), and the Conductor treats it as the merge target. Pass --base-branch develop to cut from and merge back to develop instead — useful for hotfixes or feature branches that should not target main. Start-point resolution order: explicit --base-branch → local <mainBranch> ahead of origin → origin/<mainBranch> → local <mainBranch> → HEAD (see docs/spec/05-install-and-infrastructure.md for details).

Agent / Conductor

Token Pool

Manual vs subscription tokens

• manual — A persistent API key. cmux-team stores the token in macOS keychain (service cmux-team-token) and injects CLAUDE_CODE_OAUTH_TOKEN into spawned agents.
• --subscription — A Claude Max subscription. Claude Code itself manages auth via ~/.claude/.credentials.json and refreshes the token as needed. cmux-team does not keep a keychain snapshot and does not inject the token into agents — it lets Claude Code handle authentication and only observes the requests through the proxy to track utilization. Use this for any subscription-backed handle.

Diagnostics

Slash Commands (run within Claude)

Architecture

┌─────────────────────────────────────────┐
│  cmux-team daemon (TypeScript/bun)      │
│  ┌───────────────────────────────────┐  │
│  │  TUI Dashboard                    │  │
│  │  Tasks: 2 open | Conductors: 1/3  │  │
│  └───────────────────────────────────┘  │
│  Queue ← Master/Hook write via CLI      │
│  Loop  → Task scan → Conductor spawn    │
│  Monitor → Completion → Result collect   │
└───────────┬────────────┬────────────────┘
            │            │
     [Master]    [Conductor-035]
     Claude Code  Claude Code
     (Opus)       → [Agent] Claude Code

Deterministic Manager

The Manager is not a Claude Code session. It's a TypeScript program with a deterministic event loop:

• HTTP message queue via the built-in proxy (cmux-team send <TYPE>) — event-driven, not polling
• File-based task state (.team/tasks/ + task-state.json)
• zod schema validation for all messages
• ink TUI dashboard
• Task dependency resolution via depends_on field
• Priority sorting (high > medium > low)
• Agent completion via fs.watch — Agent's Stop / SessionEnd hook writes a done marker, Conductor awaits it with cmux-team await-agent (no busy polling, T181)

Task Dependencies

---
id: 13
title: Consolidated report
status: ready
depends_on: [10, 11, 12]  # waits for all to complete
---

Communication

Project-Specific Agent Instructions

You can give each overlay role (10 in total: researcher / architect / planner / design-reviewer / implementer / inspector / dockeeper / task-manager / master / conductor) a project-local overlay by writing .team/agent-instructions/<role>.md. The overlay content is injected into the corresponding prompt:

• Agent roles (8) — overlay is applied at cmux-team spawn-agent time (replaces {{PROJECT_INSTRUCTIONS}} in the agent prompt-file).
• master / conductor (T342) — overlay is applied as a shared system-prompt overlay at daemon start: generateMasterPrompt / generateConductorRolePrompt injects it into .team/prompts/master.md / .team/prompts/conductor-role.md. They cannot be passed to cmux-team spawn-agent --role (it returns exit 1 with a "reserved" error).

# Write an overlay
cmux-team set-agent-instructions --role implementer --from-file ./my-impl-notes.md
cmux-team set-agent-instructions --role researcher --body "Limit search to papers from 2025 onward"
cmux-team set-agent-instructions --role master --body "Always summarise progress in 3 lines"
cmux-team set-agent-instructions --role conductor --from-file ./conductor-overlay.md

# Inspect / list
cmux-team get-agent-instructions --role implementer
cmux-team list-agent-instructions

# Delete (idempotent)
cmux-team delete-agent-instructions --role implementer

Max overlay size is 100 KB. The dashboard's Settings tab (4 key) shows a read-only preview of all role overlays plus a config snapshot.

Token Pool

When you have multiple Claude accounts, cmux-team can automatically distribute Agent spawns across them to avoid rate limits.

Enable (opt-in, per-project):

// .team/config.json
{ "tokenPool": { "enabled": true } }

Or via env: CMUX_TEAM_TOKEN_POOL=1.

Register tokens (macOS Keychain required for manual; subscription does not use keychain):

# Manual API key (interactive, stored in keychain)
cmux-team token add

# Claude Max subscription (no keychain, Claude Code-managed auth)
cmux-team token add --subscription @tayo --plan max-x20 --tags any

cmux-team token list     # show all tokens with 5h/7d utilization

Selection algorithm (per Agent spawn):

1. Exclude handles in policy.exclude
2. Skip tokens with active lease (120 s) or util_5h > 95%
3. Admit by: projectDefault match → include list → isOss flag → tag match ("any")
4. Score = 0.3 × util_5h + 0.7 × util_7d — pick the lowest

The TUI dashboard header shows the 7-day forecast sparkline (Day 0..6 daily allocation, 100% = sustainable pace under the BLOCKER_7D=0.95 cap) and the next account the agent spawn will pick:

pool 7d  ██▇▅▅▆█   next: @kddi 5h:65%

Per-surface decoration (@handle <5h:X%/7d:Y%> cap:Z%) is removed in favor of the aggregate header. Run cmux-team pool status for per-account detail.

See docs/spec/09-token-pool.md for tag filtering, exclude/include policy, and plan ratio details.

Traceability

All API requests are automatically recorded through the built-in proxy when the daemon is running.

Inspecting a Task's Sessions

# Show session history for a specific task (Conductor + Agents)
cmux-team trace-task 035

Traces are stored in .team/traces/traces.db with request/response bodies in .team/logs/traces/bodies/. Metadata headers (x-cmux-task-id, x-cmux-conductor-surface, x-cmux-role) are propagated so every API request can be correlated with its originating task.

Troubleshooting

Daemon won't start

bun not installed: brew install oven-sh/bun/bun

Not in cmux: Run inside cmux. CMUX_SOCKET_PATH must be set.

Panes too narrow

Too many panes cause cmux commands to fail. Exit the cmux session (daemon auto-stops) and restart with CMUX_TEAM_MAX_CONDUCTORS=1 to limit concurrency.

View Conductor session logs

grep conductor-xxx .team/logs/manager.log
# → task_completed ... session=abc-123
claude --resume abc-123

Known Limitations

• API rate limits: Multiple concurrent agents. Claude Max recommended. Control with CMUX_TEAM_MAX_CONDUCTORS (default: 3).
• Pane width: Too many panes can break cmux commands.
• Trust prompts: New directories trigger trust confirmation. Conductor auto-approves but may need manual intervention.

Testing

⚠️ Do NOT run bun test against the whole manager directory. The full-suite invocation suffers O(N²) slowdown and may hang for 30+ minutes (see .team/artifacts/A021-research.md). Use the per-file loop:

hljs language-bash

Copy

cd skills/cmux-team/manager
for f in *.test.ts state-machine/*.test.ts dashboard-*.test.tsx; do
  bun test --timeout 30000 "$f" || echo "FAIL: $f"
done

CI (.github/workflows/test.yml) runs the same per-file loop on every PR and on push to main. The aggregate-mode invocation will be restored once the root cause (module-level singleton accumulation) is fixed.

Contributing

See CONTRIBUTING.md for testing, repository structure, and coding conventions.

License

MIT License — see LICENSE for details.