From cmux-team
Orchestrates multi-agent development via cmux with 4-layer architecture: Master creates tasks, Manager daemon delegates to Conductor for git worktree agent spawning, monitoring, and result synchronization.
npx claudepluginhub hummer98/cmux-team --plugin cmux-teamThis skill uses the workspace's default tool permissions.
4層アーキテクチャ(Master → Manager → Conductor → Agent)による
manager/agent-instructions.test.tsmanager/agent-instructions.tsmanager/agent-strategy.test.tsmanager/agent-strategy.tsmanager/artifact.tsmanager/browser-open.test.tsmanager/browser-open.tsmanager/bun.lockmanager/classify-stop.test.tsmanager/classify-stop.tsmanager/claude-code-backend.test.tsmanager/claude-code-backend.tsmanager/cleanup.test.tsmanager/cleanup.tsmanager/cmux.test.tsmanager/cmux.tsmanager/conductor.test.tsmanager/conductor.tsmanager/config.test.tsmanager/config.tsProvides read-only reference for cmux-team multi-agent orchestration tool: concepts, 4-layer architecture, installation, CLI commands, task lifecycle, git worktree isolation, troubleshooting. Activates on 'help', 'how to use cmux-team', 'what is' queries.
Orchestrates hierarchical multi-AI teams in cmux workspaces deploying Claude, Gemini, Codex as independent processes for parallel execution on architecture, design, backend/frontend, QA tasks from TASKS.md.
Coordinates multiple Claude Code instances as agent teams for workflows needing inter-agent communication. Covers TeamCreate, SendMessage types, task coordination, hooks, and orchestration patterns.
Share bugs, ideas, or general feedback.
4層アーキテクチャ(Master → Manager → Conductor → Agent)による 自律的マルチエージェント開発オーケストレーションスキル。
[ユーザー] ↔ [Master] → [Manager (daemon)] → [Conductor (常駐)] → [Agent (実作業)]
│ │ │ │ │
│ │ │ │ ├─ コード実装
│ │ │ │ ├─ テスト実行
│ │ │ │ └─ 完了→停止
│ │ │ │
│ │ │ ├─ git worktree 内で作業
│ │ │ ├─ Agent 起動・監視(タブとして作成)
│ │ │ ├─ 結果統合
│ │ │ ├─ タスクを close(cmux-team close-task)
│ │ │ └─ done マーカー作成→idle に戻る
│ │ │
│ │ ├─ タスク検出→idle Conductor にタスク割り当て
│ │ ├─ done マーカーで完了検出(pull 型)
│ │ └─ Journal 読み取り + ログ記録 + Conductor リセット
│ │
│ ├─ タスク作成
│ ├─ 真のソース直接参照→報告
│ └─ Manager 健全性確認
│
└─ 指示・確認
| 層 | 責務 | 特徴 |
|---|---|---|
| Master | ユーザー対話。タスク作成。真のソース直接参照で進捗報告。 | 作業しない。ポーリングしない。 |
| Manager | daemon として常駐。[TASK_CREATED] 通知で起床→タスク検出→idle Conductor にタスク割り当て→done マーカーで完了検出→ログ記録→Conductor リセット→アイドル化。 | アイドル時停止、イベント駆動。 |
| Conductor | 常駐。タスクを割り当てられると自律実行。git worktree 隔離。Agent spawn(タブ)→結果統合→タスクを close(cmux-team close-task)→done マーカー作成→idle に戻る。 | 常駐。タスク完了後も停止しない。 |
| Agent | 実作業(実装・テスト・リサーチ等)。 | 完了したら停止。上位が見に来る。 |
| 方向 | 手段 |
|---|---|
| Master → Manager | .team/tasks/ + task-state.json + cmux send 通知(イベント駆動) |
| Manager → Conductor | cmux send(/clear + 新プロンプト送信) |
| Manager ← Conductor | done マーカーファイル(.team/output/conductor-N/done)の存在確認(pull 型) |
| Conductor → Agent | cmux send(プロンプト送信) |
| Conductor ← Agent | cmux-team await-agent(done マーカーの fs.watch)+ PID watcher |
| Manager → Master | .team/logs/manager.log + cmux-team status(team.json + ログ) |
| コマンド | 説明 |
|---|---|
/master | Master ロール再読み込み(/clear 後の復帰用) |
/team-spec | 要件ブレスト(Master が直接ユーザーと対話) |
/team-task | タスク管理(タスクの作成・一覧・クローズ) |
/team-archive | 完了タスクのアーカイブ(closed → archived) |
/artifact | 知見のアーティファクト化(作成・一覧・表示) |
チーム体制の構築・管理はすべて CLI 経由で行う:
| コマンド | 説明 |
|---|---|
cmux-team start | daemon 起動 + Master spawn + レイアウト構築(レイアウト消失時は自己修復。T286) |
cmux-team status | ステータス表示(team.json + ログ末尾) |
cmux-team send TASK_CREATED | タスク作成通知(--task-id, --task-file 必須) |
cmux-team send TODO | TODO 通知(--content 必須) |
cmux-team send SHUTDOWN | シャットダウン通知(内部用。明示停止は kill <pid>) |
cmux-team spawn-agent | Agent spawn(--conductor-surface, --role, --prompt or --prompt-file) |
cmux-team agents | 稼働中エージェント一覧 |
cmux-team kill-agent | Agent 終了(--surface 必須、--conductor-surface 任意) |
cmux-team create-task | タスク作成(--title 必須、--priority, --status, --body, --depends-on, --base-branch, --run-after-all, --exclusive 任意) |
cmux-team update-task | タスク状態更新(--task-id, --status 必須) |
cmux-team close-task | タスククローズ(--task-id 必須、--journal 任意) |
cmux-team await-task | タスク完了待ち(--task-id 必須、--timeout 任意) |
cmux-team trace | API トレース検索(--task, --search, --show) |
cmux-team get-agent-instructions | Agent ロールの overlay を表示(--role 必須) |
cmux-team set-agent-instructions | overlay を書き込み(--role 必須、--body / --from-file / --from-stdin) |
cmux-team delete-agent-instructions | overlay を削除(--role 必須、存在しなければ exit 0) |
cmux-team list-agent-instructions | 全ロールの overlay 状況を一覧表示 |
プロジェクト固有の Agent への追加指示を .team/agent-instructions/<role>.md に置くと、cmux-team spawn-agent 実行時に prompt-file 中の {{PROJECT_INSTRUCTIONS}} プレースホルダがその内容で置換される。
researcher / architect / planner / design-reviewer / implementer / inspector / dockeeper / task-manager の 8 ロール。
--role impl は implementer、--role reviewer は design-reviewer にエイリアスされる(conductor-role.md の既存 heredoc 例との互換性維持)。
# overlay を書き込む
cmux-team set-agent-instructions --role implementer --from-file ./my-impl-notes.md
cmux-team set-agent-instructions --role researcher --body "調査対象は 2025 年以降の論文に限る"
cat ./notes.md | cmux-team set-agent-instructions --role planner --from-stdin
# 内容確認
cmux-team get-agent-instructions --role implementer
cmux-team list-agent-instructions
# 削除
cmux-team delete-agent-instructions --role implementer
overlay ファイルは最大 100 KB。それを超えると set 時に exit 1。
cmux-team spawn-agent --prompt-file <path> 実行時、prompt-file 内の {{PROJECT_INSTRUCTIONS}} プレースホルダが overlay 本文に展開される。Conductor が Agent 起動用の prompt-file を heredoc で書き出す際は、必ず {{PROJECT_INSTRUCTIONS}} を単独行として残すこと(quoted heredoc 'AGENT_PROMPT' を使うと shell 展開されず安全)。
overlay が存在しない / 空の場合はプレースホルダが空文字に置換される。
dashboard TUI の Settings タブ(4 キー)で 8 ロールの overlay 状況と config 値を一覧・プレビューできる(read-only)。
daemon 起動時に API Proxy が自動起動し、全 API リクエストを SQLite FTS5 データベースに記録する。Master が過去の作業ログを検索・分析する際に活用できる。
daemon が起動すると Proxy が自動で立ち上がり、Master および Conductor に ANTHROPIC_BASE_URL=http://127.0.0.1:<port> を設定する。これにより全 API リクエストが Proxy 経由になり、リクエスト/レスポンスが自動記録される。
リクエストヘッダーからメタデータを動的に抽出し、トレースに紐付ける:
| ヘッダー | 内容 |
|---|---|
x-cmux-task-id | タスクID |
x-cmux-conductor-surface | Conductor surface |
x-cmux-role | エージェントロール |
x-claude-code-session-id | Claude Code セッションID |
cmux-team trace コマンドでトレースを検索・表示できる:
# タスクIDでフィルタ
cmux-team trace --task 035
# 全文検索(SQLite FTS5)
cmux-team trace --search "error"
# 特定トレースの詳細表示(リクエスト/レスポンス本文含む)
cmux-team trace --show 42
# Conductor IDでフィルタ
cmux-team trace --conductor conductor-1
# ロールでフィルタ
cmux-team trace --role impl
# 結果数制限(デフォルト20)
cmux-team trace --limit 50
Master がユーザーに進捗報告する際、過去の API リクエスト履歴を参照できる:
# あるタスクでどんな API リクエストが行われたか確認
cmux-team trace --task 035
# エラーに関連するリクエストを全文検索
cmux-team trace --search "rate_limit"
| 変数 | 意味 |
|---|---|
CMUX_SOCKET_PATH | cmux ソケットパス。設定されていれば cmux 環境内で動作中 |
CMUX_WORKSPACE_ID | 現在のワークスペースID |
CMUX_SURFACE_ID | 現在のサーフェスID |
CMUX_SURFACE | cmux-team が設定。surface:N 形式。これが設定されていれば cmux-team 管理下 |
| コマンド | 用途 |
|---|---|
cmux identify | 自分の workspace/surface を確認 |
cmux tree | ペイン・サーフェス階層を表示(T195 以降は init 時の pane 逆引きのみ使用) |
cmux list-panes | ペイン一覧 |
cmux list-pane-surfaces | ペイン内のサーフェス一覧 |
cmux new-split right | 右にペイン分割(left/up/down も可) |
cmux new-surface --pane pane:N | ペイン内に新しいタブを作成 |
cmux send --surface surface:N "command\n" | コマンド送信 |
cmux send-key --surface surface:N return | キー送信 |
cmux read-screen --surface surface:N | 画面読み取り |
cmux close-surface --surface surface:N | サーフェス(タブ)を閉じる |
cmux rename-tab --surface surface:N "name" | タブ名変更 |
cmux refresh-surfaces | 画面バッファ強制更新 |
単一行: 末尾に \n を付ける。
cmux send --surface surface:1 "echo hello\n"
複数行: 個別の send + send-key return で送信する。
cmux send --surface surface:1 "line 1"
cmux send-key --surface surface:1 return
cmux send --surface surface:1 "line 2"
cmux send-key --surface surface:1 return
注意: \n は最後の1つだけが Enter として機能する。途中の \n は改行にならない。
send-key を使う(send ではない):
cmux send-key --surface surface:N ctrl+c # 中断
cmux send-key --surface surface:N ctrl+d # EOF
cmux send-key --surface surface:N ctrl+z # サスペンド
cmux send-key --surface surface:N return # Enter
cmux send-key --surface surface:N tab # Tab
cmux send-key --surface surface:N escape # Escape
よくある間違い: cmux send "C-c" や cmux send "\x03" → 動作しない。必ず send-key を使うこと。
| 問題 | 対処 |
|---|---|
| 空・古い出力 | cmux refresh-surfaces してからリトライ |
| 出力が切れる | --scrollback オプションを追加 |
| 特定行数だけ必要 | --lines N オプションを追加 |
| surface が見つからない | cmux list-pane-surfaces で確認 |
# アプリ内通知(ペイン強調 + サイドバーバッジ)
cmux notify --title "完了" --body "ビルドが成功しました"
# macOS 通知センター(サウンド付き)
osascript -e 'display notification "ビルド完了" with title "Claude" sound name "Glass"'
cmux-team await-task はタスクの完了を fs.watch ベースで待機する CLI コマンド。
cmux-team status のポーリングに比べて軽量・高速で、Claude Code の Bash run_in_background と組み合わせることで Master がブロックされずにタスク完了を待てる。
# 単一タスクの完了を待つ
cmux-team await-task --task-id 108
# 複数タスクの完了を待つ(カンマ区切り)
cmux-team await-task --task-id 108,109
# タイムアウト指定(デフォルト: 3600秒)
cmux-team await-task --task-id 108 --timeout 7200
| コード | 意味 | stdout/stderr |
|---|---|---|
| 0 | 全タスク closed | summary.md の内容を stdout に出力 |
| 1 | いずれかのタスクが aborted | abort 理由を stderr に出力 |
| 2 | タイムアウト | 残タスク一覧を stderr に出力 |
# バックグラウンドでタスク完了を待つ(Claude Code の Bash run_in_background)
cmux-team await-task --task-id 108
# → task-notification で完了が通知される + summary が読める
# 「結果を見てから次を判断」するフロー
cmux-team await-task --task-id 108
# 完了後に summary を読んで次のアクションを決定
| 方式 | 用途 |
|---|---|
depends-on (frontmatter) | 自動チェーン: A → B の順序保証。Manager が自動で B を発火 |
await-task (CLI) | 手動チェーン: A の結果を見てから次を判断するケース |
タスク frontmatter で表現される実行制御属性。create-task の CLI フラグで指定すると永続化される。
| 属性 | 意味 | CLI フラグ |
|---|---|---|
run_after_all: true | 全 open タスク closed 後に実行(非排他 drain) | --run-after-all |
exclusive: true | drain 後に単独実行。assigned の間は他の全 assignment を停止(closed 後に再開)。--run-after-all を暗黙に含む | --exclusive |
ready で待機--exclusive 同士は共存可能(ID 昇順に順次排他実行)--exclusive ↔ 非排他 --run-after-all は共存不可(どちら側から起票しても RUN_AFTER_ALL_CONFLICT)--run-after-all 同士は 1 つまで(従来通り)--run-after-all と --exclusive を同時指定すると警告のみで処理継続