cmux-team
Multi-agent development orchestration with Claude Code + cmux.
Why cmux-team?
Claude Code's built-in sub-agents (the Agent tool) are useful, but you can't see what they're doing. You only get the final result — the process is a black box.
cmux-team uses cmux's terminal splitting to run sub-agents visibly in parallel.
What you do: Just give Claude instructions in natural language. What Claude does: Splits panes via cmux, launches sub-agents, monitors them, and integrates results.
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
Works without Nerd Font (falls back to Unicode symbols). Setbrew install --cask font-hack-nerd-fontCMUX_NERD_FONT=0to use fallback icons explicitly.
Installation
npm install -g @hummer98/cmux-team
Usage
Basic Workflow
Start cmux, launch Claude Code inside it.
You: /cmux-team:start
→ Daemon starts with TUI dashboard
→ Master pane auto-created
→ Switch to Master pane to give tasks
You: Build a TODO app with React
Claude: Task created.
→ Daemon detects task → spawns Conductor
→ Conductor spawns Agents in adjacent panes
→ 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 (TODO)
Claude: → Sends TODO to queue via CLI
→ Daemon spawns new Conductor in parallel
Commands
CLI Commands (run from terminal)
| Command | What it does | When to use |
|---|---|---|
cmux-team start | Start daemon + Master + Conductors | Once per session |
cmux-team status | Show team status | Anytime |
cmux-team stop | Graceful shutdown | When done |
cmux-team create-task | Create a task | Task creation |
cmux-team trace | Search API traces | Debugging, analysis |
cmux-team artifacts | List / show / search artifacts | Knowledge management |
Slash Commands (run within Claude)
| Command | What it does | When to use |
|---|---|---|
/cmux-team:master | Reload Master role | After /clear |
/team-spec [summary] | Brainstorm requirements | Deciding what to build |
/team-task [action] | Task management | Record decisions |
/team-archive [range] | Archive closed tasks | Task cleanup |
/artifact [type] [title] | Save findings as artifact | Knowledge capture |
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:
- File queue (
.team/queue/) for communication (nocmux send-key) - zod schema validation for all messages
- ink TUI dashboard
- Task dependency resolution via
depends_onfield - Priority sorting (high > medium > low)
Task Dependencies
---
id: 13
title: Consolidated report
status: ready
depends_on: [10, 11, 12] # waits for all to complete
---
Communication
| Direction | Mechanism |
|---|---|
| Master → daemon | CLI (main.ts send) → .team/queue/*.json |
| daemon → Conductor | cmux new-split + Claude Code launch |
| Conductor → daemon | SessionEnd hook + cmux list-status polling |
Traceability
All API requests are automatically recorded through the built-in proxy when the daemon is running.
Searching Traces
# Filter by task ID
cmux-team trace --task 035
# Full-text search (SQLite FTS5)
cmux-team trace --search "error"
# Show trace details (including request/response bodies)
cmux-team trace --show 42
Traces are stored in .team/traces/traces.db with request/response bodies in .team/logs/traces/bodies/.
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.