Cmux Team Guide

cmux-team ユーザーガイド

1. cmux-team とは

cmux のターミナルマルチプレクサ機能を活用し、Claude Code の複数セッションを協調させて開発タスクを自律的に遂行するマルチエージェントオーケストレーションツール。

4層アーキテクチャ:

[ユーザー] ↔ [Master] → [Manager (daemon)] → [Conductor (常駐)] → [Agent (実作業)]

設計原則: 上位が下位を pull 型で監視（push 報告に依存しない）。各層は自分の仕事だけをする。全作業は git worktree で隔離され main は常に安全。

作業隔離（git worktree）

全てのタスクは .worktrees/<taskRunId>/ 内で実行される。main ブランチは常に安全。

• タスク割り当て時: worktree を自動作成
• 成功時: worktree 内でコミット → main にマージ → worktree 削除
• 失敗時: worktree 強制削除 + ブランチ削除
• 手動クリーンアップ: git worktree list で確認、git worktree remove <path> --force で削除

2. インストール・起動

前提: cmux がインストール済み、Claude Code が利用可能（Claude Max 推奨）。

# インストール
npm install -g @hummer98/cmux-team

# 起動（cmux 内で実行）
cmux-team start
# → daemon 起動 + Master spawn + 3 Conductor 配置
# → 固定2x2レイアウトが構築される

# 停止は不要（cmux 終了で daemon も自動停止。手動停止は `kill <pid>` で）

レイアウト（固定2x2）:

[Manager|Master] | [Conductor-1]
[Conductor-2   ] | [Conductor-3]

• 左上: Manager（daemon）と Master（ユーザーセッション）がタブとして同居
• 右上〜右下: Conductor-1〜3（常駐 Claude セッション）
• 4ペインは不動。サブエージェントは Conductor ペイン内にタブとして作成される
• 最大3タスク並列、4つ目以降はキューイング

3. タスク管理

ライフサイクル: draft → ready → assigned → closed/aborted

• deleted: draft/ready から delete-task で遷移
• archived: closed から /team-archive で遷移

# タスク作成（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 "理由"

オプション:

• 依存関係: --depends-on 40,41 で指定。依存タスクが全て closed になるまで実行されない
• マージ先ブランチ: --base-branch develop で指定可能（デフォルトは main）

重要: タスクファイル（.team/tasks/）への直接編集は禁止。必ず CLI を使うこと。

4. CLI コマンド一覧

各コマンドの詳細は cmux-team <command> --help で確認可能。

他プロジェクトを覗く（T440）: 全コマンドに --project-root <path> フラグを追加可能。読み系（status / agents / events / metrics / trace-task 等）は無条件で受理される。書き込み系（start / create-task / update-task / close-task / spawn-* / send 等）は cwd と異なる root への書き込みを confirmation gate で防ぐ。bypass は --project-root-confirm フラグまたは CMUX_TEAM_PROJECT_ROOT_CONFIRM=1 env で可能（CI / 自動化向け）。詳細は docs/spec/05-install-and-infrastructure.md の「Project root 解決」を参照。

5. スラッシュコマンド（Claude 内で使用）

6. TUI ダッシュボード

cmux-team start で自動起動するフルスクリーン TUI。

表示内容:

• ヘッダー: ステータス、PID、稼働時間、プロキシポート、レート制限使用率、token pool 7d forecast、Web dashboard URL
• Conductor 一覧: 各 Conductor の状態（idle/running）、割り当てタスク、エージェント数
• タスクリスト: open タスク（上位）+ closed タスク（下位）
• Journal/Log タブ: タスク完了履歴、daemon ログ
• Artifacts タブ: 知見の一覧
• Settings タブ: config と全 10 ロールの overlay プレビュー
• Issues タブ: GitHub issues 一覧（Ctrl+R で gh sync）
• Metrics タブ: 集計サマリと Web dashboard URL（O でブラウザ起動。詳細は docs/spec/12-web-dashboard.md）

キーボードショートカット (T435 で Vim ベースに統一):

旧キー (T J L A I M B O / r / Q / Ctrl+R) は v.next で削除予定の deprecated alias として残置。単発 g と Ctrl+G は alias なしで完全廃止（chord prefix conflict のため）。詳細は ? で表示される overlay を参照。

進捗確認の真のソース:

7. Artifacts（知見の記録）

会話中の調査結果・設計判断・セッション要約を構造化して保存する機能。

cmux-team artifacts              # 一覧
cmux-team artifacts show A001    # 表示
cmux-team artifacts open A001    # Markdown ビューアで開く
cmux-team artifacts search "認証" # 全文検索
cmux-team artifacts add file.md  # ファイルを追加

タイプ: research, decision, session, spec, report 保存先: .team/artifacts/Axxx-<slug>.md

Markdown viewer の解決順 (T439): CMUX_TEAM_MD_VIEWER env → mado（yamamoto/mado、Electrobun ベース GUI viewer。検出時は detached 起動して即 return）→ cat（TUI を一時停止）。dashboard の Artifacts タブから Enter でも同じ経路。pbcopy で絶対パスをクリップボードにコピーしたい場合は c c chord を使う。

スラッシュコマンド /artifact でも作成・表示可能。

8. トラブルシューティング