tmux-ops-bundle

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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

The Tmux Ops Bundle is a comprehensive toolkit designed for Miyabi multi-agent AI orchestration. It streamlines complex AI workflows by providing advanced tmux session management, real-time health monitoring, and automated session recovery. By integrating task queues and MCP server coordination, it ensures seamless communication between specialized agents (Conductor, CodeGen, Review, Deploy), preventing context exhaustion and maintaining high operational uptime for autonomous AI development environments.

Use Cases

  • 1. Multi-Agent Development Pipelines: Orchestrating a team of AI agents where specialized roles (Conductor, CodeGen, Reviewer, Deployer) work in parallel within a structured tmux environment to automate the full software development lifecycle.
  • 2. Automated AI Session Recovery: Automatically monitoring agent health and context levels, triggering recovery protocols like '/clear' or pane respawns when agents hit context limits or become unresponsive.
  • 3. Structured Agent Communication: Implementing the P0.2 PUSH protocol to allow workers to autonomously report progress to a conductor agent, reducing latency and overhead in multi-agent coordination.
  • 4. Real-time AI Observability: Utilizing a dedicated tracker dashboard to monitor context usage, task queues, and activity logs across multiple concurrent AI agent sessions to prevent performance degradation.
nametmux-ops-bundle
version2.0.0
description|
authorMiyabi Team
updated2025-12-06

🎯 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 役割割り当て