agent-manager

エージェントマネージャー

tmux セッションで AI エージェントを管理するための、従業員エージェントのオーケストレーションシステムです。CAO に代わる、シンプルで依存関係の少ない選択肢です。

クイックスタート

# Project-local install path varies by tool. If `.agent/skills/` doesn't exist, try `.claude/skills/`.
# List all agents
python3 .agent/skills/agent-manager/scripts/main.py list
python3 .claude/skills/agent-manager/scripts/main.py list

# (use the same path you chose above for the remaining commands)
# Start dev agent
python3 .agent/skills/agent-manager/scripts/main.py start dev

# Monitor output (live)
python3 .agent/skills/agent-manager/scripts/main.py monitor dev --follow

# Assign task
python3 .agent/skills/agent-manager/scripts/main.py assign dev <<EOF
Fix the login bug in the auth module
EOF

# Stop agent
python3 .agent/skills/agent-manager/scripts/main.py stop dev

コマンドパスの統一（ドキュメントの基準）

README.md やランブックの例との一貫性を保つため、CLI エイリアスを 1 つ定義し、セッション内で再利用します。

# Installed skill path (pick one that exists)
CLI="python3 .agent/skills/agent-manager/scripts/main.py"
# CLI="python3 .claude/skills/agent-manager/scripts/main.py"

# If operating from a cloned repo instead of installed skill:
# CLI="python3 agent-manager/scripts/main.py"

$CLI doctor
$CLI list
$CLI status EMP_0001

主な概念

エージェント設定

エージェントは、YAML フロントマターを含む agents/EMP_*.md ファイルで定義します。

---
name: dev
description: Dev Agent (project-agnostic)
working_directory: ${REPO_ROOT}
launcher: ${REPO_ROOT}/projects/claude-code-switch/ccc
launcher_args:
  - cp
  - --dangerously-skip-permissions
skills:
  - review-pr
  - bsc-contract-development
---

# DEV AGENT

## Role and Identity
You are the Dev Agent...

フィールド：

• name：エージェント識別子（dev、qa）
• description：エージェントの説明
• enabled：エージェントを起動できるかどうか（デフォルトは true、無効にするには false を設定）
• working_directory：デフォルトの作業ディレクトリ（${REPO_ROOT} をサポート）
• launcher：フルパスまたはプロバイダー名
• launcher_args：ランチャーの引数
• launcher_config：任意のランチャー／プロバイダー固有の起動設定
• skills：.agent/skills/ にあるスキル名の配列（任意、起動時に挿入）
• schedules：スケジュール済みジョブの配列（任意、「スケジューリング」セクションを参照）
• tmux：任意の tmux レイアウトメタデータ（レイアウト＋対象ペイン）

tmux セッション

各エージェントは専用の tmux セッション（agent-{name}）で実行されます。

• 簡単なモニタリング：tmux capture-pane -t agent-dev
• 直接操作：tmux attach -t agent-dev
• 明確な分離：プロセスが混在しません

オプション：tmux レイアウト

tmux レイアウトを自動作成し、特定のペインでエージェントを起動できます。

tmux:
  layout:
    split: h
    panes:
      - {}
      - split: v
        panes:
          - {}
          - {}
  target_pane: "1.1"

注：

• split：h（左右）または v（上下）を指定します。horizontal／vertical も使用できます。
• target_pane：レイアウトツリー内の 0／1 インデックスをピリオドで区切ったパスです。 0 は左／上、1 は右／下です。"1.1" は右から下を意味します。
• tmux.layout を設定する場合、tmux.target_pane も必須です。

ランチャーの種類

フルパス：ローカルの Claude Code ランチャー

launcher: ${REPO_ROOT}/projects/claude-code-switch/ccc
launcher_args: ["cp", "--dangerously-skip-permissions"]

プロバイダー名：CAO プロバイダー（任意の統合）

launcher: droid
launcher_args: []

プロバイダー名：OpenAI Codex CLI

launcher: codex
launcher_args:
  - --model=gpt-5.2
launcher_config:
  model_instructions_file: ${REPO_ROOT}/agents/EMP_0001/prompt/shade-main-model.md

launcher_config は、ランチャー／プロバイダー固有の起動設定を指定するための汎用的な拡張ポイントです。各 CLI プロバイダーは、このフラットなマッピングをそれぞれの起動フラグに変換します（Codex の場合、各エントリは -c key=value になります）。

プロバイダー名：Kimi Code CLI

launcher: kimi
launcher_args:
  - --auto

Kimi Code プロバイダーに関する注記：セッションの復元には --session <id> を使用します。システムプロンプトの挿入には現在、tmux のペーストによるフォールバックを使用します。起動時に MCP 設定は挿入されません。

予約済みの main エージェントでは、launcher: codex が使用され、ワークスペースのエージェント設定で launcher_config.model_instructions_file が明示的に上書きされていない場合、バンドルされたスキルプロンプト agent-manager/.codex/main-codex-model.md がデフォルトで使用されます。

注：スケジュール済みジョブでは、agent-manager がベストエフォートで Codex の初回起動時／アップグレード時のモデル選択プロンプトを自動で閉じ、cron の実行が対話なしで行われるようにします。

コマンド

以下の例では、「コマンドパスの統一（ドキュメントの基準）」で $CLI をすでに定義しているものとします。

list - すべてのエージェントを一覧表示

設定済みのエージェントとそのステータスをすべて表示します。

$CLI list              # All agents
$CLI list --running    # Only running

出力：

📋 Agents:

✅ Running dev (session: agent-dev)
   Description: Dev Agent (project-agnostic)
   Working Dir: /home/user/repo
   Skills: review-pr, bsc-contract-development

⭕ Stopped qa
   Description: QA Agent in a multi-agent system
   Working Dir: /home/user/repo/projects/CloudBank-feat-invite-code

⛔ Disabled old-dev
   Description: Legacy Dev Agent (deprecated)
   Working Dir: /home/user/repo

start - エージェントを起動

tmux セッションでエージェントを起動します。

$CLI start dev                      # Use default working_dir
$CLI start dev --working-dir /path   # Override working dir

• すでに実行中の場合は拒否します（1 エージェントにつき 1 ターミナル）
• エージェントが無効になっている場合（設定の enabled: false）は拒否します
• スキルを読み込み、システムプロンプトとして挿入します
• セッション名は agent-{name} です

stop - 実行中のエージェントを停止

エージェントの tmux セッションを停止（終了）します。

$CLI stop dev

status - エージェントのステータスを表示

実行中かどうか、ランタイムの状態、最新のハートビートマーカー／イベントなど、1 つのエージェントのランタイムスナップショットを表示します。

$CLI status dev

monitor - エージェントの出力をモニタリング

tmux セッションからエージェントの出力を表示します。

$CLI monitor dev              # Last 100 lines
$CLI monitor dev -n 500       # Last 500 lines
$CLI monitor dev --follow     # Live monitoring (Ctrl+C to stop)

send - エージェントにメッセージを送信

実行中のエージェントにメッセージ／コマンドを送信します。

$CLI send dev "Please run tests"
$CLI send dev --no-enter "Draft message only"

デフォルトでは、send はメッセージをすぐに送信します（Enter も自動的に送信されます）。 送信せずに入力するには、--no-enter を使用します。

message - エージェント間プロトコルメッセージ

3 つのセクションで構成される、最小限のエージェント間プロトコルエンベロープを作成または送信します。 必須の Meta、必須の Body、および任意のプレーンテキストの Footer 返信ヒントです。

# Print an envelope to stdout only
$CLI message compose --from EMP_0001 --to EMP_0017 --body "Review PR #123."

# Send a protocol message through tmux
$CLI message send EMP_0017 --from EMP_0001 --body "Review PR #123." --footer "Reply with QA Verdict: PASS/FAIL."

# Send a protocol reply
$CLI message reply --from EMP_0017 --to EMP_0001 --reply-to msg_20260724_153012_ab12cd34 --body "QA Verdict: PASS"

このプロトコルがインストールされていない可能性のあるエージェントに送信する場合は、Footer を次の 1 文にしてください：Read the agent-manager skill's message protocol and reply with reply_to: msg_20260724_153012_ab12cd34.

エンベロープの形式：

--- Meta ---
id: msg_20260724_153012_ab12cd34
type: message
from: EMP_0001
to: EMP_0017

--- Body ---
Review PR #123.

--- Footer ---
Reply with QA Verdict: PASS/FAIL.

Meta は意図的に最小限の構成になっています：id、type（message または reply）、from、to、および返信用の任意の reply_to です。Body はプレーンテキストで、複数行にできます。 Footer は任意で、プレーンテキストのみを指定でき、返信ヒントに限って使用してください。 エージェント間の互換性を確保するため、プロトコルの説明を埋め込むのではなく、受信者に agent-manager スキルを案内する 1 文の Footer を推奨します。

このプロトコルはステートレスです。受信トレイ／送信トレイのファイル、確認応答、再試行、再生記録、スレッドログは作成しません。コマンドの成功は tmux の送信操作が成功したことのみを意味します。送信側は引き続き、配信と処理を確認する責任を負います。

assign - エージェントへのタスクの割り当て

エージェントにタスクを割り当てます（実行中でなければ起動します）。

# From stdin
$CLI assign dev <<EOF
🎯 Task: Fix the login bug

1. Reproduce the issue
2. Identify root cause
3. Implement fix
4. Add tests
EOF

# From file
$CLI assign dev --task-file task.md

assign は自動的に送信するため（デフォルトで Enter が送信されます）、tmux で手動で Enter を押す必要はありません。

エージェントの無効化

エージェントが起動されないよう、一時的に無効化できます（メンテナンス、テスト、または廃止に役立ちます）。

エージェントを無効にする

エージェントの YAML フロントマターに enabled: false を追加します。

---
name: dev
description: Dev Agent (project-agnostic)
enabled: false  # ← Agent cannot be started
working_directory: ${REPO_ROOT}
launcher: ${REPO_ROOT}/projects/claude-code-switch/ccc
---

動作

エージェントが無効な場合：

• ⛔ list コマンドに「無効」ステータスが表示されます
• ⚠️ start コマンドはエラーメッセージとともに拒否されます
• schedule sync は無効なエージェントのすべてのスケジュールをスキップします
• 実行中のセッションは自動的には停止しません（手動での停止が必要です）

再度有効にするには： enabled: true を設定するか、このフィールドを削除します（デフォルトは true です）

使用例

• メンテナンス：設定を更新する間、エージェントを一時的に無効にする
• テスト：テスト中にスケジュールされたエージェントが実行されないようにする
• 廃止：ファイルを削除する前に、エージェントを廃止対象としてマークする

スケジュール設定

cron 式を使用して、エージェントがスケジュールに従って自動的に実行されるように設定できます。

スケジュール設定

エージェントの YAML フロントマターに schedules 配列を追加します。

---
name: dev
description: Dev Agent
working_directory: ${REPO_ROOT}
launcher: ${REPO_ROOT}/projects/claude-code-switch/ccc
launcher_args:
  - cp
  - --dangerously-skip-permissions
skills:
  - bsc-contract-development

schedules:
  - name: daily-standup
    cron: "0 9 * * 1-5"
    task: |
      Review GitHub issues, prioritize today's work
    max_runtime: 30m

  - name: code-review
    cron: "0 14 * * 1-5"
    task_file: ${REPO_ROOT}/tasks/templates/code-review.md
    max_runtime: 2h

  - name: weekly-report
    cron: "0 17 * * 5"
    task: |
      Generate weekly progress report and commit to docs/
    max_runtime: 1h
    enabled: true
---

スケジュールのフィールド：

フィールド	型	必須	説明
name	string	✓	一意のジョブ識別子
cron	string	✓	cron 式（例：0 9 * * 1-5）
task	string	△	タスクの説明（インライン）
task_file	string	△	タスクファイルのパス（${REPO_ROOT} をサポート）
max_runtime	string		最大実行時間（例：30m、2h、8h）
enabled	bool		デフォルト：true

注：task または task_file のいずれかを指定する必要があります。

スケジュールコマンド

schedule list - スケジュール済みの全ジョブを一覧表示

$CLI schedule list

出力：

📅 Scheduled Jobs:

dev (EMP_0001):
  ✓ daily-standup         0 9 * * 1-5          (30m)
  ✓ code-review           0 14 * * 1-5         (2h)
  ✓ weekly-report         0 17 * * 5           (1h)

qa (EMP_0002):
  ✓ nightly-tests         0 2 * * *            (4h)

schedule sync - スケジュールを Crontab に同期

すべてのエージェントのスケジュールをシステムの Crontab に同期します。

# Preview changes (dry run)
$CLI schedule sync --dry-run

# Apply changes
$CLI schedule sync

これにより、次のような Crontab エントリが生成されます：

# === agent-manager schedules (auto-generated) ===
# dev (EMP_0001)
# daily-standup
0 9 * * 1-5 cd /path/to/repo && python3 /absolute/path/to/agent-manager/scripts/main.py schedule run dev --job daily-standup >> /tmp/agent-emp-0001-daily-standup.log 2>&1
# === end agent-manager schedules ===

schedule run - スケジュール済みのジョブを手動で実行

スケジュール済みのジョブを手動で実行します（テストに役立ちます）。

$CLI schedule run dev --job daily-standup

# Override timeout
$CLI schedule run dev --job daily-standup --timeout 1h

ハートビート

ハートビートは、実行中のエージェントに標準のチェックインメッセージを送信する、特別な種類の定期ジョブです。エージェントごとに複数のジョブを設定できるスケジュールとは異なり、各エージェントに設定できるハートビートは 0 または 1 件 です。

ハートビートの設定

エージェントの YAML フロントマターに heartbeat 辞書を追加します：

---
name: dev
description: Dev Agent
working_directory: ${REPO_ROOT}
launcher: codex
launcher_args:
  - --model=gpt-4.7
  - --dangerously-bypass-approvals-and-sandbox

heartbeat:
  cron: "*/30 * * * *"  # Every 30 minutes
  max_runtime: 5m
  session_mode: auto     # restore | auto | fresh
  mode: normal           # normal (use `timer` for delayed rescue; `full_speed` is legacy)
  dream:
    enabled: true
    idle_after: 1h       # Optional idle-window trigger after normal HEARTBEAT_OK cycles
    max_runtime: 30m
    fixed_windows:       # During these windows heartbeat dispatch sends DREAM.md tasks
      - timezone: Asia/Shanghai
        start: "23:00"
        end: "08:00"
  enabled: true
---

ハートビートのフィールド：

フィールド	型	必須	説明
cron	string	✓	Cron 式（例：*/30 * * * *）
max_runtime	string		最大実行時間（例：5m、10m）
session_mode	string		セッションポリシー：restore（デフォルト）、auto（コンテキストが 25% 未満になるとロールオーバー）、fresh（ハンドオフ後は常にロールオーバー）
mode	string		ハートビートのトリガーモード。アクティブな経路は normal のみです。full_speed は非推奨の互換性用の値で、start 中の従来の Codex フックのクリーンアップ／読み戻しのみを維持します。タイマー駆動の後続処理が、サポートされている代替手段です。
auto_starvation_skip_threshold	int		auto モード専用です。デフォルトは 3 です。連続した事前チェックのスキップ後に実行を強制するスターベーション回避を無効にするには、0 に設定します
dream	dict		オプションの Dream モードポリシーです。idle_after は既存のハートビート後の Dream タイマー動作を維持し、fixed_windows は設定された時間帯のいずれかが有効な間、ハートビートの実行を Dream タスクに切り替えます。
enabled	bool		デフォルト：true

full_speed は、標準的な実行経路ではなく、従来との互換性を示すマーカーとして扱ってください。古い Codex Stop フックが残っている場合、start によってクリーンアップされます。新しい遅延後続処理／レスキューフローでは、timer を使用してください。

固定 Dream 時間帯

heartbeat.dream.enabled が true で、現在の現地時刻が heartbeat.dream.fixed_windows のいずれかのルールに該当する場合、heartbeat run は標準のハートビートプロンプトの代わりに、標準の Dream プロンプトを送信します：

Read DREAM.md if it exists ... If nothing worth doing emerges, reply DREAM_OK.

固定時間帯では、timezone、start、end、work_days、holidays、 extra_workdays、when がサポートされています。日付をまたぐ時間帯（23:00 → 08:00）もサポートされています。work_days を省略した場合、固定 Dream 時間帯は 7 日すべてが対象になります。複数の時間帯は OR ルールとして扱われ、最初に有効になった時間帯が適用されます。

ハートビートとスケジュールの比較

機能	ハートビート	スケジュール
エージェントごと	ハートビート 0～1 件	スケジュール 0～N 件
タスク内容	固定（標準のチェックイン）	ジョブごとにカスタマイズ
動作	実行中のエージェントのみをチェック	必要に応じてエージェントを起動
用途	定期的なヘルスチェック	タスクの自動化

ハートビートコマンド

heartbeat list - すべてのハートビートジョブを一覧表示

$CLI heartbeat list

出力：

💓 Heartbeats:

dev (EMP_0001):
  ✓ heartbeat           */30 * * * *         (5m session:auto)

heartbeat sync - ハートビートを crontab に同期

ハートビートとスケジュールは、システムの crontab にまとめて同期されます。

# Preview changes (dry run)
$CLI heartbeat sync --dry-run

# Apply changes
$CLI heartbeat sync

次のような crontab エントリが生成されます：

# === agent-manager schedules (auto-generated) ===
# dev (EMP_0001)
# heartbeat [HB]
*/30 * * * * cd /path/to/repo && python3 /absolute/path/to/agent-manager/scripts/main.py heartbeat run EMP_0001 >> /path/to/.crontab_logs/agent-emp-0001-heartbeat.log 2>&1
# === end agent-manager schedules ===

heartbeat run - ハートビートを手動で実行

ハートビートを手動でトリガーします（テストに便利です）。

$CLI heartbeat run EMP_0001

# Override timeout
$CLI heartbeat run EMP_0001 --timeout 1m

ハートビートの動作：

• エージェントが無効の場合はスキップします
• エージェントが実行中でない場合はスキップします（エージェントは起動しません）
• 標準のハートビートメッセージをエージェントに送信します
• session_mode によるオプションのセッションロールオーバーに対応します（先にハンドオフを行い、その後、新しいセッションを開始）
• 応答を待機します（最大 max_runtime まで）
• auto モードでは、古くなった保留中のハートビートが、タイマーを利用した復旧経路を通じてレスキューをスケジュールまたはトリガーする場合があります

timer - 遅延アクションをスケジュール

Cron を使わずに、1 回限りの遅延アクションを実行するには timer を使用します：

# Run one heartbeat in 5 seconds
$CLI timer heartbeat main --delay 5s

# Schedule one heartbeat rescue in 5 seconds
$CLI timer rescue main --delay 5s --timeout 8m --reason auto_pending_heartbeat_rescue

# Run an arbitrary agent-manager command in 5 seconds
$CLI timer command --delay 5s -- heartbeat run main --timeout 8m

# Inspect recent timers
$CLI timer list

実行ごとに、次の場所に構造化 JSONL 監査イベントが追記されます：

.claude/state/agent-manager/heartbeat-audit/{agent_id}.jsonl

イベントのフィールド（可観測性のために標準化）：

• timestamp
• agent_id
• hb_id
• stage（標準のステージ名。デフォルトは heartbeat_attempt）
• result（success／failure／pending）
• duration（ミリ秒。duration_ms の別名）
• send_status
• ack_status
• duration_ms
• context_left
• failure_type
• session_mode
• reason_code
• attempt
• recovery_action
• reason_code

失敗の分類（failure_type）には、次の値が含まれます：

• send_fail
• no_ack
• timeout
• blocked

heartbeat trace - ハートビート監査ログを検索

# Recent events
$CLI heartbeat trace

# Filter by heartbeat id
$CLI heartbeat trace --hb-id 20260209-120001

# Filter by agent + time range (UTC)
$CLI heartbeat trace   --agent EMP_0001   --since 2026-02-09T00:00:00Z   --until 2026-02-10T00:00:00Z

# Output JSON
$CLI heartbeat trace --agent EMP_0001 --json

heartbeat slo - 日次／週次 SLO サマリー

# Daily summary (default)
$CLI heartbeat slo

# Weekly summary for one agent
$CLI heartbeat slo --window weekly --agent EMP_0001

# Explicit time window + JSON
$CLI heartbeat slo   --since 2026-02-01T00:00:00Z   --until 2026-02-08T00:00:00Z   --json

組み込みの SLO チェック：

• 成功率の目標：>= 99%
• タイムアウト率の目標：<= 2%
• 復旧 p95 の目標：<= 120000ms

単独で実行できるサマリースクリプト（同じ指標）：

python3 scripts/heartbeat_slo.py --window daily
python3 scripts/heartbeat_slo.py --window weekly --agent EMP_0001 --json

標準のハートビートメッセージ

ハートビートは、エージェントに次のメッセージを送信します。

Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.

対応が必要なことがなければ、エージェントは HEARTBEAT_OK を返すか、HEARTBEAT.md の内容に基づいて対応します。

スキルの統合

エージェントは .agent/skills/ のスキルを参照できます。

skills:
  - review-pr
  - bsc-contract-development
  - cao

エージェントの起動時に、スキルの内容がシステムプロンプトとして挿入されます。

## Available Skills

### review-pr
Code review skill for GitHub PRs and local changes...

### bsc-contract-development
Comprehensive BSC smart contract development expertise...

利用可能なスキル：

• bsc-contract-development - BSC スマートコントラクトの開発
• cao - CLI エージェントオーケストレーター
• collab-pr-fix-loop - QA→Dev→QA の PR イテレーション
• review-pr - PR のコードレビュー
• skill-creator - 新しいスキルの作成

アーキテクチャ

.agent/skills/agent-manager/
├── SKILL.md                    # This file
├── scripts/
│   ├── main.py                 # CLI entry point
│   ├── heartbeat_slo.py        # Heartbeat SLO summary script
│   ├── agent_config.py         # Agent file parser
│   ├── tmux_helper.py          # Tmux wrapper
│   └── schedule_helper.py      # Crontab management
├── providers/
│   └── __init__.py             # CLI provider configs
└── references/
    └── task_templates.md       # Optional task templates

設計原則

1. CAO への依存なし：必要なのは tmux と Python のみです
2. プロバイダーパターンから着想：CAO を参考にしつつ、シンプルに実装します
3. tmux ネイティブ：各エージェントを独自の tmux セッションで実行します
4. YAML Frontmatter：既存のエージェントファイル形式を活用します
5. 環境変数：${REPO_ROOT} の展開に対応します
6. エージェントごとにターミナルを 1 つ：重複した起動を拒否します

CAO との比較

機能	CAO	Agent Manager
依存関係	CAO サーバー、uvx、requests	tmux、Python のみ
複雑さ	高（HTTP API、プロバイダー）	低（tmux を直接使用）
セッション管理	CAO サーバー	ネイティブ tmux
監視	HTTP API 呼び出し	ネイティブ tmux
拡張性	プロバイダーシステム	スクリプトを直接編集
インストール	CAO サーバーのセットアップ	サーバー不要
ユースケース	複雑なワークフロー	シンプルなエージェント管理

エラー処理

• tmux がインストールされていない：インストールコマンドを含む明確なエラーを表示します
• エージェントが見つからない：利用可能なエージェントを一覧表示します
• すでに実行中：先に停止するよう促します
• 実行されていない：先に起動するよう促します

ランブックのチェックリスト

運用引き継ぎとインシデント対応には、次を使用します。

• agent-manager/docs/runbook-checklist.md

次の内容が含まれています。

• 新規参加者向けの 30 分間のセルフチェック手順
• ハートビート応答なしのトラブルシューティング SOP
• セッション停止時の復旧 SOP
• CI／QA のマージゲート用チェックリストとエビデンステンプレート

高度な使い方

Tmux を直接操作する

# Attach to agent session (interactive)
tmux attach -t agent-dev

# Detach from session: Ctrl+b, then d

# Capture output manually
tmux capture-pane -p -t agent-dev -S -100

# List all agent sessions
tmux ls | grep ^agent-

ワークフローの例

# Morning: Start agents
$CLI start dev
$CLI start qa

# Assign task to dev
$CLI assign dev <<EOF
Implement the user profile feature:
1. Profile update API
2. Profile view component
3. Integration tests
EOF

# Quick runtime snapshot
$CLI status dev

# Monitor progress
$CLI monitor dev --follow

# Send clarification if needed
$CLI send dev "Please add validation for email format"

# After dev completes, assign to QA
$CLI assign qa <<EOF
Review the user profile feature:
- Security check
- Edge cases
- Test coverage
EOF

# Evening: Stop agents
$CLI stop dev
$CLI stop qa