cmux-team（CMUX 团队）

cmux-team: マルチエージェントオーケストレーション

4層アーキテクチャ（Master → Manager → Conductor → Agent）による 自律的マルチエージェント開発オーケストレーションスキル。

0. アーキテクチャ概要

4層構造

[ユーザー] ↔ [Master] → [Manager (daemon)] → [Conductor (常駐)] → [Agent (実作業)]
    │            │              │                       │                      │
    │            │              │                       │                      ├─ コード実装
    │            │              │                       │                      ├─ テスト実行
    │            │              │                       │                      └─ 完了→停止
    │            │              │                       │
    │            │              │                       ├─ git worktree 内で作業
    │            │              │                       ├─ Agent 起動・監視（タブとして作成）
    │            │              │                       ├─ 結果統合
    │            │              │                       ├─ タスクを close（cmux-team close-task）
    │            │              │                       └─ done マーカー作成→idle に戻る
    │            │              │
    │            │              ├─ タスク検出→idle Conductor にタスク割り当て
    │            │              ├─ done マーカーで完了検出（pull 型）
    │            │              └─ Journal 読み取り + ログ記録 + Conductor リセット
    │            │
    │            ├─ タスク作成
    │            ├─ 真のソース直接参照→報告
    │            └─ Manager 健全性確認
    │
    └─ 指示・確認

各層の責務

通信方式

1. コマンド一覧

スラッシュコマンド（Claude 内）

CLI サブコマンド

チーム体制の構築・管理はすべて CLI 経由で行う:

2. トレーサビリティ

daemon 起動時に API Proxy が自動起動し、全 API リクエストを SQLite FTS5 データベースに記録する。Master が過去の作業ログを検索・分析する際に活用できる。

自動プロキシ設定

daemon が起動すると Proxy が自動で立ち上がり、Master および Conductor に ANTHROPIC_BASE_URL=http://127.0.0.1:<port> を設定する。これにより全 API リクエストが Proxy 経由になり、リクエスト/レスポンスが自動記録される。

メタデータ伝播

リクエストヘッダーからメタデータを動的に抽出し、トレースに紐付ける:

trace CLI

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"

3. cmux 操作リファレンス

環境変数

基本操作コマンド

send の改行ルール（重要）

単一行: 末尾に \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 を使うこと。

read-screen トラブルシューティング

通知

# アプリ内通知（ペイン強調 + サイドバーバッジ）
cmux notify --title "完了" --body "ビルドが成功しました"

# macOS 通知センター（サウンド付き）
osascript -e 'display notification "ビルド完了" with title "Claude" sound name "Glass"'

4. タスク完了待ち（await-task）

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

終了コード

Master での活用パターン

# バックグラウンドでタスク完了を待つ（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 との使い分け