# 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.

- Skill: `majiayu000/tmux-ops-bundle` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/tmux-ops-bundle`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/tmux-ops-bundle/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/tmux-ops-bundle

---


# 🎯 Tmux Ops Bundle v2.0

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

## 🚀 30秒クイックスタート

```bash
# 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統合](#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 | 監視ダッシュボード（オプション） |

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

```bash
#!/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 (必須)

```bash
# 絶対に守るフォーマット - 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
   ポーリングは禁止
   リソース浪費・レイテンシ増加
```

### メッセージフォーマット

```bash
# 標準報告
[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消失 | 完全再構築 |

### 自動復旧スクリプト

```bash
#!/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連携

```bash
# タスク作成
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)
```

### ワークフロー例

```bash
# 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

```javascript
// セッション一覧
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

```javascript
// 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` | 役割割り当て |