1. What is cmux-team
A multi-agent orchestration tool that leverages cmux's terminal multiplexer functionality to coordinate multiple Claude Code sessions and autonomously carry out development tasks.
4-layer architecture:
[ユーザー] ↔ [Master] → [Manager (daemon)] → [Conductor (常駐)] → [Agent (実作業)]
| Layer | Responsibility |
|---|---|
| Master | User interaction. Task creation and progress reporting. Does not do the work |
| Manager | TypeScript daemon. Task detection → assignment to Conductor → completion detection → logging |
| Conductor | Resident Claude session. Autonomously executes tasks. Isolated via git worktree. Launches and monitors Agents |
| Agent | Actual work (implementation, testing, research, etc.). Stops when complete |
Design principles: Upper layers monitor lower layers in a pull-based manner (does not rely on push reports). Each layer does only its own job. All work is isolated in git worktrees, so main is always safe.
Work isolation (git worktree)
All tasks are executed within .worktrees/<taskRunId>/ . The main branch is always safe.
- At task assignment: Automatically create worktree
- On success: Commit in worktree → merge into main → delete worktree
- On failure: Force-delete worktree + delete branch
- Manual cleanup:
git worktree listCheck withgit worktree remove <path> --forcedelete with
2. Installation and startup
Prerequisites: cmux is installed, Claude Code is available (Claude Max recommended).
# インストール
npm install -g @hummer98/cmux-team
# 起動（cmux 内で実行）
cmux-team start
# → daemon 起動 + Master spawn + 3 Conductor 配置
# → 固定2x2レイアウトが構築される
# 停止は不要（cmux 終了で daemon も自動停止。手動停止は `kill <pid>` で）
Layout (fixed 2x2):
[Manager|Master] | [Conductor-1]
[Conductor-2 ] | [Conductor-3]
- Top left: Manager (daemon) and Master (user session) share the space as tabs
- Top right to bottom right: Conductor-1 to 3 (resident Claude sessions)
- The 4 panes are fixed. Subagents are created as tabs within the Conductor pane
- Up to 3 tasks in parallel, the 4th and beyond are queued
3. Task management
Lifecycle: draft → ready → assigned → closed/aborted
deleted: from draft/ready todelete-taskTransition witharchived: from closed to/team-archiveTransition with
# タスク作成（draft で作成、ready にすると Conductor に自動割り当て）
cmux-team create-task --title "機能Xを追加" --status draft --body "説明文"
# タスクを実行可能にする
cmux-team update-task --task-id 42 --status ready
# タスククローズ（Conductor が自動実行、手動も可）
cmux-team close-task --task-id 42 --journal "完了サマリー"
# タスク中止
cmux-team abort-task --task-id 42 --journal "理由"
# 実行中タスクの再実行（assigned を ready に戻す）
cmux-team restart-task --task-id 42
# タスク削除（draft/ready のみ）
cmux-team delete-task --task-id 42 --journal "理由"
Options:
- Dependencies:
--depends-on 40,41specified with. Not executed until all dependent tasks are closed - Merge target branch:
--base-branch developcan be specified with (default is main)
Important: Task file (.team/tasks/) is prohibited. Always use the CLI.
4. CLI command list
| Command | Description |
|---|---|
cmux-team start |
Start daemon + spawn Master + build layout (self-repairs when layout is lost. T286) |
cmux-team status |
Display status |
cmux-team create-task |
Create task (--title, --status, --body, --priority, --depends-on, --base-branch, --run-after-all） |
cmux-team update-task |
Update task (--task-id, --status, --title, --body, --depends-on） |
cmux-team close-task |
Task close (--task-id, --journal, --force） |
cmux-team abort-task |
Abort task (--task-id, --journal） |
cmux-team restart-task |
assigned / aborted Restart the task's Conductor session (status back to ready , clear assignment info such as worktree / sessionId, and also support resuming from aborted in T204) (--task-id, --journal） |
cmux-team delete-task |
Delete task (--task-id, --journal） |
cmux-team spawn-agent |
Start Agent (--conductor-surface, --role, --prompt or --prompt-file） |
cmux-team agents |
List of running agents |
cmux-team kill-agent |
Terminate Agent (--surface） |
cmux-team trace |
API trace search (--task, --search, --show, --conductor, --role, --limit） |
cmux-team trace-hooks |
hook signal history search (--type, --surface, --task-run, --limit(default 50), --json）。T217 |
cmux-team artifacts |
Artifact management (subcommands: add, show, open, search. Options: --validate） |
cmux-team metrics |
Aggregate summary of task lifecycle / tool call / token (--since <range>, --group-by day, --format csv). Subcommands: snapshot / compare / health / query(DuckDB ad-hoc). For details, see docs/spec/11-metrics.md |
cmux-team events |
events stream（.team/logs/events.jsonl）を tail / filter（--follow, --types <names>, --format json|tsv). For details, see docs/spec/10-events-stream.md |
cmux-team spawn-conductor [--resume <session-id>] [--task-prompt <path>] [--model <model>] |
Start and register Claude Code for Conductor (internal use).--resume restore existing session with--task-prompt atomically inject the prompt as a CLI argument at startup (T421/D7) |
For details on each command, see cmux-team <command> --help .
Peek at another project (T440): You can add the --project-root <path> flag to all commands. Read-type commands (status / agents / events / metrics / trace-task ) are accepted unconditionally. Write-type commands (start / create-task / update-task / close-task / spawn-* / send ) are prevented by a confirmation gate from writing to a root different from cwd. Bypass is possible with the --project-root-confirm flag or CMUX_TEAM_PROJECT_ROOT_CONFIRM=1 env (for CI / automation). For details, see docs/spec/05-install-and-infrastructure.md "Project root resolution".
5. Slash commands (used within Claude)
| Command | Description |
|---|---|
/master |
Reload Master role (/clear for recovery after) |
/team-spec |
Interactively brainstorm requirements and formulate specifications |
/team-task |
Manage task creation, listing, closing, and display |
/team-archive |
Archive completed tasks (closed → archived) |
/artifact |
Structure and save knowledge as artifacts |
/docs-sync |
Sync docs/spec/ with the implementation |
6. TUI Dashboard
cmux-team start A full-screen TUI that starts automatically with
Displayed content:
- Header: status, PID, uptime, proxy port, rate limit usage, token pool 7d forecast, Web dashboard URL
- Conductor list: each Conductor's state (idle/running), assigned tasks, number of agents
- Task list: open tasks (upper) + closed tasks (lower)
- Journal/Log tab: task completion history, daemon log
- Artifacts tab: list of knowledge
- Settings tab: config and overlay preview of all 10 roles
- Issues tab: GitHub issues list (
Ctrl+Rで gh sync） - Metrics tab: aggregate summary and Web dashboard URL (
Oto open in browser. For details, seedocs/spec/12-web-dashboard.md）
Keyboard shortcuts (unified to Vim-based in T435):
| Key | Action |
|---|---|
? |
Show help overlay (list of all keys) |
1〜6 / Tab / gt / gp |
Switch tabs (Journal/Artifacts/Log/Settings/Issues/Metrics) |
↑/↓ / j/k |
Move cursor |
gg / ge |
Jump to start / end of list (Vim chord) |
Ctrl+d / Ctrl+u |
Half-page scroll |
Enter / o |
Open selected item (Artifacts is mado or cat） |
c c |
Artifacts tab: Copy the absolute path of the selected artifact to the clipboard with pbcopy (a second cwithin 500ms, cancel with another key, show success/failure toast. T439) |
Ctrl+o |
Open in browser (Issues / Metrics) |
Ctrl+s |
Re-sync from gh in the Issues tab |
Ctrl+r |
Reload |
q |
Exit TUI (daemon continues) |
Ctrl+q |
Full quit (close all surfaces and shut down) |
Esc |
Cancel / return to global focus |
Old key (
T J L A I M B O/r/Q/Ctrl+R) is kept as a deprecated alias scheduled for removal in v.next. The singlegとCtrl+Gis fully removed with no alias (due to chord prefix conflict). For details, see the overlay shown with?.
True sources for progress checking:
| Information | How to check |
|---|---|
| Manager status | TUI dashboard header |
| Conductor status | TUI Conductor section or cmux tree |
| Task progress | TUI Tasks panel or .team/task-state.json |
| Completion history | TUI Journal tab or .team/logs/manager.log |
7. Artifacts (Recording Knowledge)
A feature that structurally saves investigation results, design decisions, and session summaries from conversations.
cmux-team artifacts # 一覧
cmux-team artifacts show A001 # 表示
cmux-team artifacts open A001 # Markdown ビューアで開く
cmux-team artifacts search "認証" # 全文検索
cmux-team artifacts add file.md # ファイルを追加
Type: research, decision, session, spec, report
Save location: .team/artifacts/Axxx-<slug>.md
Markdown viewer resolution order (T439): CMUX_TEAM_MD_VIEWER env → mado(yamamoto/mado, an Electrobun-based GUI viewer. When detected, launch detached and return immediately) → cat(pause the TUI). From the dashboard's Artifacts tab, Enter also follows the same path.pbcopy If you want to copy the absolute path to the clipboard with c c chord.
Slash command /artifact can also be used to create and display.
8. Troubleshooting
| Problem | Workaround |
|---|---|
| A trust confirmation is displayed | It is auto-approved on first launch, but depending on timing, manual Enter may be required |
| API rate limit | Claude Max recommended. The TUI displays rate limit usage. New allocations are temporarily paused above 90% |
| Conductor crashes | Manager detects and aborts.cmux-team restart-task Re-run with |
| Agent crashes | Conductor detects and respawns |
| Manager crashes | cmux-team start . Assigned tasks automatically resume |
| The TUI freezes | q Exit the TUI with cmux-team start then restart with |
| Task remains assigned | cmux-team abort-task Abort withcmux-team restart-task and re-run with |