tmux-ops-bundle

name	tmux-ops-bundle
version	2.0.0
description	Advanced tmux operations bundle for Miyabi multi-agent AI orchestration. Includes auto-recovery, health monitoring, task queue integration, and MCP server coordination. The definitive skill for AI agent workflows.
triggers	["tmux ops","multi-agent","orchestrate agents","session management","recover session","agent communication","PUSH protocol","broadcast","monitor agents","health check","task queue"]
author	Miyabi Team
updated	"2025-12-06T00:00:00.000Z"

🎯 Tmux Ops Bundle v2.0

高度なマルチエージェントAI開発環境の構築・運用・監視・自動復旧

🚀 30秒クイックスタート

# 1. セッション作成（4エージェント自動起動）
bash scripts/create-agent-session.sh PROJECT /path/to/project

# 2. 監視開始
bash scripts/agent-tracker-v2.sh

# 3. 接続
tmux attach -t PROJECT

---

📋 目次

1. セッション管理
2. 通信プロトコル
3. エージェント監視
4. 自動復旧
5. タスクキュー統合
6. オーケストレーション
7. MCP統合
8. トラブルシューティング

---

セッション管理

アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                    Tmux Session                             │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────┐  ┌─────────────────────┐          │
│  │ %53 しきるん        │  │ %55 カエデ          │          │
│  │ Conductor           │  │ CodeGen             │          │
│  │ タスク統括・分配    │  │ コード実装          │          │
│  └─────────────────────┘  └─────────────────────┘          │
│  ┌─────────────────────┐  ┌─────────────────────┐          │
│  │ %56 サクラ          │  │ %57 ツバキ          │          │
│  │ Review              │  │ Deploy              │          │
│  │ コードレビュー      │  │ Git/PR/デプロイ     │          │
│  └─────────────────────┘  └─────────────────────┘          │
│  ┌─────────────────────────────────────────────────────────┤
│  │ %58 Tracker (Optional)                                  │
│  │ リアルタイム監視ダッシュボード                          │
│  └─────────────────────────────────────────────────────────┤
└─────────────────────────────────────────────────────────────┘

役割定義

Pane	Agent	役割	責務
0	しきるん	Conductor	タスク統括・分配・進捗集約・Guardian報告
1	カエデ	CodeGen	コード実装・リファクタリング・型安全性
2	サクラ	Review	コードレビュー・品質保証・アクセシビリティ
3	ツバキ	Deploy	Git操作・PR作成・デプロイ・統合テスト
4	Tracker	Monitor	監視ダッシュボード（オプション）

セッション作成スクリプト

#!/bin/bash
# scripts/create-agent-session.sh

SESSION=${1:-"agents"}
PROJECT_DIR=${2:-$(pwd)}

tmux new-session -d -s $SESSION -c $PROJECT_DIR -n main
tmux split-window -h -t $SESSION:main -c $PROJECT_DIR
tmux split-window -v -t $SESSION:main.0 -c $PROJECT_DIR
tmux split-window -v -t $SESSION:main.2 -c $PROJECT_DIR
tmux select-layout -t $SESSION:main tiled

# Claude Code起動
for i in 0 1 2 3; do
    tmux send-keys -t $SESSION:main.$i "claude --dangerously-skip-permissions" Enter
    sleep 1.5
done

---

通信プロトコル

P0.2 Protocol (必須)

# 絶対に守るフォーマット - sleep 0.5 は省略禁止
tmux send-keys -t %PANE_ID 'MESSAGE' && sleep 0.5 && tmux send-keys -t %PANE_ID Enter

PUSH vs PULL

✅ PUSH (Required): Worker → Conductor
   エージェントは自発的にConductorに報告する
   処理オーバーヘッドを最小化

❌ PULL (Forbidden): Conductor → Worker
   ポーリングは禁止
   リソース浪費・レイテンシ増加

メッセージフォーマット

# 標準報告
[Agent名] {Status}: {Detail}

# Status一覧
# 開始/Started   - タスク開始
# 進行中/Working - 作業中
# 完了/Complete  - 完了
# エラー/Error   - 失敗
# 待機/Waiting   - 依存待ち
# ブロック/Blocked - 進行不可

# エージェント間リレー
[Sender→Receiver] {Action}: {Detail}

# 例
[カエデ] 完了: navigation-sidebar.tsx 実装完了
[カエデ→サクラ] レビュー依頼: PR #245
[サクラ→ツバキ] PR作成依頼: レビュー承認済み

---

エージェント監視

コンテキストレベル管理

Level	状態	アクション
30%+	🟢 OK	継続
10-29%	🟡 LOW	監視強化
<10%	🔴 CRITICAL	即座に /clear
<5%	⚠️ EMERGENCY	自動復旧発動

Tracker v2 機能

• リアルタイムコンテキスト監視
• 自動復旧（<5%で自動clear）
• タスクキュー表示
• アクティビティログ
• キーボードショートカット

---

自動復旧

復旧レベル

Level	状況	対応
1	コンテキスト低下	/clear
2	Pane応答なし	respawn-pane -k
3	Window消失	new-window + 再構築
4	Session消失	完全再構築

自動復旧スクリプト

#!/bin/bash
# scripts/auto-recover.sh

for pane in 53 55 56 57; do
    ctx=$(tmux capture-pane -t "%$pane" -p 2>/dev/null | tail -5 | \
          grep -o 'auto-compact: [0-9]*' | sed 's/auto-compact: //' | tail -1)
    ctx=${ctx:-100}
    
    if [ "$ctx" -lt 5 ]; then
        echo "⚠️ EMERGENCY: %$pane at ${ctx}% - Auto clearing..."
        tmux send-keys -t "%$pane" "/clear" Enter
        sleep 0.5
    fi
done

---

タスクキュー統合

DevIssue連携

# タスク作成
miyabi-github:dev_issue_create {
  title: "UI改善: navigation-sidebar.tsx",
  priority: "P1-High",
  labels: ["カエデ", "frontend"]
}

# タスク一覧
miyabi-github:dev_issue_list { status: "queued" }

# GitHub同期
miyabi-github:dev_issue_sync { owner: "user", repo: "project" }

タスク優先度

Priority	対応時間	例
P0-Critical	即座	本番障害、セキュリティ
P1-High	1時間以内	重要機能、ブロッカー
P2-Medium	当日中	通常機能、改善
P3-Low	次スプリント	リファクタ、技術負債

---

オーケストレーション

パイプラインパターン

Sequential (直列):
  Issue → CodeGen → Review → PR → Deploy

Parallel (並列):
         ┌→ CodeGen-1 ─┐
  Issue →├→ CodeGen-2 ─┼→ Review → PR → Deploy
         └→ CodeGen-3 ─┘

Review Loop (再レビュー):
  CodeGen → Review → [Pass] → PR
                ↓
            [Fail] → CodeGen (fix)

ワークフロー例

# 1. しきるんがIssue受領・分析
[しきるん] 開始: Issue #123 分析中

# 2. カエデに実装指示
[しきるん→カエデ] タスク割当: Issue #123 - UI改善

# 3. カエデが実装完了報告
[カエデ] 完了: navigation-sidebar.tsx 実装完了

# 4. サクラにレビュー依頼
[カエデ→サクラ] レビュー依頼: feature/issue-123 ブランチ

# 5. サクラがレビュー完了
[サクラ] レビュー完了: LGTM, 軽微な指摘あり

# 6. ツバキにPR作成依頼
[サクラ→ツバキ] PR作成依頼: レビュー承認済み

# 7. ツバキがPR作成・マージ
[ツバキ] PR作成: #245 - UI改善
[ツバキ] マージ完了: #245 → main

---

MCP統合

miyabi-tmux MCP

// セッション一覧
miyabi-tmux:tmux_list_sessions

// ペイン一覧
miyabi-tmux:tmux_list_panes { session: "PROJECT" }

// メッセージ送信 (P0.2準拠)
miyabi-tmux:tmux_send_message { 
  pane_id: "%53", 
  message: "[カエデ] 完了: 実装完了" 
}

// ブロードキャスト
miyabi-tmux:tmux_broadcast { 
  message: "【全体通知】デプロイ開始" 
}

// ペイン出力取得
miyabi-tmux:tmux_pane_tail { pane_id: "%53", lines: 20 }

// ビジー状態確認
miyabi-tmux:tmux_pane_is_busy { pane_id: "%55" }

miyabi-github MCP

// Issue取得
miyabi-github:github_get_issue { issue_number: 123 }

// PR作成
miyabi-github:github_create_pr {
  head: "feature/issue-123",
  title: "feat: UI improvements",
  body: "## Changes\n- ..."
}

// DevIssue作成
miyabi-github:dev_issue_create {
  title: "Task name",
  priority: "P1-High"
}

---

トラブルシューティング

問題	原因	解決策
メッセージ未着	sleep省略	sleep 0.5 を追加
コンテキスト枯渇	長時間実行	/clear でリセット
pane応答なし	プロセス死亡	respawn-pane -k で再起動
通信遅延	同時送信過多	送信間隔を0.5秒以上に
セッション消失	サーバー再起動	create-agent-session.sh で再構築
Claude起動失敗	認証切れ	claude auth login で再認証

---

ベストプラクティス

DO ✅

1. sleep 0.5 必須 - メッセージ安定性確保
2. PUSH通信 - ワーカーは自発的に報告
3. コンテキスト監視 - 10%未満で即座にクリア
4. 構造化メッセージ - [Agent] Status: Detail 形式
5. ブランチ作業 - 必ずfeature branchで作業
6. 段階的復旧 - Level 1から順に試行

DON'T ❌

1. PULL禁止 - Conductorからのポーリング
2. sleep省略 - メッセージ破損の原因
3. 直接main - 必ずブランチ経由
4. 無限ループ - タイムアウト設定必須
5. 承認なしデプロイ - 本番は必ずGuardian承認
6. 手動介入過多 - 自動化を信頼

---

スクリプト一覧

Script	用途
create-agent-session.sh	セッション作成
agent-tracker-v2.sh	リアルタイム監視
auto-recover.sh	自動復旧
health-check.sh	ヘルスチェック
broadcast.sh	ブロードキャスト
clear-all.sh	全クリア
status.sh	ステータス確認
assign-roles.sh	役割割り当て