bg-dispatch — OpenClaw Skill

重い開発エージェント向けの Fire-and-Forget バックグラウンド ディスパッチャー。Claude Code、Aider、Codex CLI などの長時間実行の開発ツールをバックグラウンドで起動できます。OpenClaw セッションは無料のままで、トークン消費がゼロです。完了時、プラグイン可能なノーティファイアがエージェントとチームに通知します。

使用時期

bg-dispatch を使用する場合:

• 数分以上かかると予想されるコーディング作業
• 機能構築、バグ修正、リファクタリング、テスト記述
• メインセッションをブロックしてしまう重い「バイブコーディング」セッション
• 他の会話でエージェントが利用可能にしたい作業

直接処理する場合(ディスパッチなし):

• ドキュメント編集のみ(README、設定ファイル)
• クイックな単一行シェルコマンド
• 結果がすぐに必要な作業

クイックリファレンス

新規タスクをディスパッチする

bg-dispatch \
  --adapter claude-code \
  --prompt "Build a REST API with user authentication and rate limiting" \
  --name "user-auth-api" \
  --workdir /path/to/project \
  --source-session "$CURRENT_SESSION_KEY"

割り込み後に再開する

bg-dispatch --adapter claude-code --workdir /path/to/project --resume --force

タスクステータスを確認する(ハートビート)

node task-check.mjs --data-dir ./data --projects-dir /path/to/projects

利用可能なアダプター

claude-code(Claude Code)

プライマリアダプター。Superpowers プラグイン、Agent Teams、Bedrock に対応しています。

bg-dispatch -a claude-code \
  -p "Implement the payment module with Stripe integration" \
  -n "payment-stripe" \
  -w /path/to/project \
  --model "claude-opus-4-1-20250805" \
  --agent-teams \
  --allowed-tools "Bash(*),Read,Write,Edit,MultiEdit,Glob,Grep,Skill,Agent"

アダプター固有のオプション:

• --opt permission-mode=none — Claude Code パーミッションモード

環境変数:

• CLAUDE_BIN — claude バイナリへのパス(デフォルト:自動検出)
• CLAUDE_CODE_USE_BEDROCK=1 — AWS Bedrock を使用
• AWS_PROFILE, AWS_REGION — Bedrock 認証

aider(Aider)

bg-dispatch -a aider \
  -p "Refactor the database layer to use connection pooling" \
  -n "db-pool-refactor" \
  -w /path/to/project \
  --model "claude-sonnet-4-20250514"

アダプター固有のオプション:

• --opt edit-format=diff — 編集フォーマット(whole/diff/udiff)
• --opt auto-commits=true — Aider の自動コミット有効化
• --opt lint-cmd="ruff check" — 編集後のリント
• --opt test-cmd="pytest" — 編集後のテスト

codex(OpenAI Codex CLI)

bg-dispatch -a codex \
  -p "Add comprehensive test coverage for the auth module" \
  -n "auth-tests" \
  -w /path/to/project

アダプター固有のオプション:

• --opt approval-mode=full-auto — 承認モード(full-auto/suggest/ask)

ノーティフィケーションシステム

bg-dispatch はプラグイン可能なノーティファイアシステムを使用します。bg-dispatch.json で設定します:

{
  "notifiers": [
    {
      "type": "openclaw",
      "config": { "session": "main" }
    },
    {
      "type": "webhook",
      "config": {
        "url_env": "SLACK_WEBHOOK_URL",
        "template": "slack"
      }
    },
    {
      "type": "webhook",
      "config": {
        "url_env": "FEISHU_WEBHOOK_URL",
        "template": "feishu",
        "secret_env": "FEISHU_WEBHOOK_SECRET"
      }
    },
    {
      "type": "command",
      "config": {
        "command": "echo Task $BGD_TASK_NAME completed with status $BGD_STATUS"
      }
    }
  ]
}

ノーティファイアタイプ

タイプ	説明	ユースケース
openclaw	ダイレクトシステムイベント経由で OpenClaw セッションを起動	プライマリ — エージェントが完了イベントを受け取る
webhook	任意の webhook URL への HTTP POST	チーム通知(Slack、Feishu、Discord)
command	任意のシェルコマンドを実行	カスタム統合、スクリプト、ログ記録

Webhook テンプレート

• slack — Slack Block Kit メッセージ、ステータス、期間、モデル情報付き
• feishu — Feishu リッチテキスト投稿、絵文字ステータスインジケーター付き
• discord — Discord エンベッド、カラーコード化されたステータス付き
• generic — シンプル JSON ペイロード(任意の webhook レシーバーで動作)

設定ファイルの検索順序

1. <workdir>/bg-dispatch.json — プロジェクト別設定
2. <data-dir>/bg-dispatch.json — インスタンス設定
3. <install-dir>/bg-dispatch.json — グローバル設定
4. ~/.bg-dispatch.json — ユーザー設定

設定ファイルが見つからない場合、デフォルトは openclaw ノーティファイアになります。

カスタムノーティファイアの作成

notifiers/ に以下を実装するスクリプトを作成します:

notifier_validate() {
  # 前提条件をチェック、失敗時は 1 を返す
}

notifier_send() {
  local META_FILE="$1"  # task meta.json へのパス
  local CONFIG="$2"     # ノーティファイア設定の JSON 文字列
  # 通知を送信、成功時は 0 を返す
}

command ノーティファイアは、コマンドコンテキストで以下の環境変数を公開します:

• BGD_TASK_NAME, BGD_STATUS, BGD_EXIT_CODE
• BGD_WORKDIR, BGD_MODEL, BGD_ADAPTER
• BGD_STARTED_AT, BGD_COMPLETED_AT
• BGD_META_FILE, BGD_PROGRESS_FILE

動作原理

アーキテクチャ

Your Agent (OpenClaw session)
  │
  ├─ Receives coding task
  ├─ Runs: bg-dispatch --adapter <name> --prompt <task> --workdir <dir>
  │   ├─ Creates progress.md + meta.json in data/tasks/<task-id>/
  │   ├─ Launches coding agent in background (setsid + PTY)
  │   ├─ Starts watchdog (stall detection + max runtime)
  │   └─ Returns immediately ← your agent is FREE
  │
  ... zero token consumption while agent works ...
  │
  ├─ On completion:
  │   ├─ Hook fires → notify.sh → all configured notifiers
  │   ├─ Watchdog provides fallback if hook fails
  │   └─ OpenClaw notifier wakes your agent session (instant, no cron delay)
  │
  ├─ Your agent reads data/tasks/<task-id>/progress.md
  └─ Sends summary to user, creates PR, etc.

3 階層通知保証

1. フック(プライマリ) — Claude Code の Stop フック発火 → on-complete.sh → notify.sh
2. プロセスフォールバック — バックグラウンドプロセスのインライン完了ハンドラー
3. ウォッチドッグ(セーフティネット) — プロセス終了を検出、フック待機 35 秒、逃した場合は送信

3 つのパスすべてが notify.sh を呼び出します。これはべき等です:各ノーティファイアは送信前に meta.json の notified.* フィールドをチェックします。最初のライターが勝ち、後続の呼び出しは安全な no-op です。フックと setsid ブロック レースが発生していても重複通知はありません。

カスケーディングセッション起動(openclaw ノーティファイア)

openclaw ノーティファイアは、ターゲットセッションが一時的に利用不可でも、エージェントセッションが確実に起動されるように 3 レベルのカスケードを使用します:

Level 1: Targeted session wake (source_session)
  │ ✅ → done (notification delivered to exact originating session)
  │ ❌ ↓
Level 2: Broadcast system event (main session)
  │ ✅ → done (main session picks up the completion)
  │ ❌ ↓
Level 3: Heartbeat pending marker
  │ → writes pending_session_notify to meta.json
  │ → next heartbeat poll (task-check.mjs) surfaces it
  └ → agent reads meta.json and delivers the notification

--source-session: ディスパッチ時に発信セッションキーを渡します。完了通知は、メインセッションにブロードキャストするのではなく、そのセッションに直接ルーティングされます(レベル 1)。ディスパッチセッション(例:Slack チャネル)とメインエージェントセッションが異なるマルチチャネルセットアップでは重要です。

bg-dispatch -a claude-code \
  -p "Fix auth bug" \
  -n "auth-fix" \
  -w /path/to/project \
  --source-session "channel:C0ANTPRBBJ4"

meta.json のべき等性追跡:

{
  "notified": {
    "openclaw": true,
    "webhook_slack": true,
    "webhook_feishu": false
  },
  "pending_session_notify": null
}

pending_session_notify が null でない場合、task-check.mjs はハートビートが配信を再試行できるように出力に含めます。

ウォッチドッグの動作

• スタル検出 — ファイル変更なしで 15 分(設定可能) → キル + 通知
• 最大ランタイム — ハード 2 時間制限(設定可能) → キル + 通知
• Progress.md チェック — ## Status: COMPLETE が表示されたら → クリーンシャットダウン + 通知
• 終了検出 — プロセス終了時、フック待機、必要に応じてフォールバック送信

進行状況の監視

bg-dispatch はディスパッチと完了の間の中間進行状況レポートを提供します:

• 定期的なポーリング — --progress-interval 300 で、ウォッチドッグは 5 分ごとに git diff --stat を実行し、progress.md に追加します
• ファイルアクティビティシグナル — ウォッチドッグはファイル変更を watchdog.log に記録し、meta.json の last_activity を更新します(常時オン)
• 進行状況通知 — ノーティファイアは events 設定配列経由で progress イベントをサブスクライブできます
• ライブ出力 — bgd logs -f はタスク実行中にリアルタイムで出力をフォローします

ノーティファイアイベント設定

各ノーティファイアは特定のイベントをサブスクライブできます。デフォルトは ["complete"] のみ:

{
  "notifiers": [
    { "type": "openclaw", "config": { "session": "main" } },
    { "type": "webhook", "config": { "url_env": "SLACK_WEBHOOK_URL", "template": "slack" }, "events": ["complete", "progress"] }
  ]
}

イベントタイプ:

• complete — タスク完了(デフォルト、フィルター処理しない限りは常に送信)
• progress — 軽量な タスク中更新(events 配列経由でオプトイン)

再開プロトコル

進行状況は data/tasks/<task-id>/ に一元化されており、プロジェクト workdir の外にあるので、リポジトリを汚しません:

data/tasks/<task-id>/
├── meta.json          # 完全なタスク定義(プロンプト、アダプター、設定、ステータス)
├── progress.md        # 完了内容、進行中、残タスク
├── output.txt         # エージェント出力ログ
└── watchdog.log       # ウォッチドッグ監視ログ

再開時、bg-dispatch は workdir に合致するタスクを data/tasks/ で検索し、meta.json からプロンプトをリビルドします。エージェントは progress.md + git log を読み、最後のチェックポイントから続行します。見つかった場合、workdir の従来の .dev-progress/ は自動的にマイグレーションされます。

CLI リファレンス

Usage: bg-dispatch [OPTIONS]

Required:
  -a, --adapter NAME         Adapter name (claude-code, aider, codex)
  -p, --prompt TEXT          Task prompt (required unless --resume)

Options:
  -n, --name NAME            Task name (default: task-<timestamp>)
  -w, --workdir DIR          Working directory (default: cwd)
  --resume                   Resume from data/tasks/
  --force                    Kill existing task for same workdir
  --model MODEL              Model override
  --allowed-tools TOOLS      Allowed tools (adapter-specific)
  --agent-teams              Enable multi-agent mode
  --stall-timeout SECS       Stall timeout (default: 900)
  --max-runtime SECS         Max runtime (default: 7200)
  --progress-interval SECS   Progress polling interval (default: 0 = disabled)
  --callback-session KEY     OpenClaw session key
  --source-session KEY       Originating session key (for targeted notification routing)
  --opt KEY=VALUE            Adapter-specific option (repeatable)
  -h, --help                 Show help

エージェント開発者向け統合ガイド

ステップ 1:インストール

git clone https://github.com/PeterHiroshi/bg-dispatch.git
cd bg-dispatch && bash install.sh
export PATH="$(pwd):$PATH"
export BG_DISPATCH_DIR="$(pwd)"

ステップ 2:通知を設定する

bg-dispatch.json を作成して、希望するノーティファイアを設定します。最低限、openclaw を使用してエージェントを起動します:

{
  "notifiers": [
    { "type": "openclaw", "config": { "session": "main" } }
  ]
}

ステップ 3:エージェントからディスパッチする

OpenClaw エージェントはこのようにタスクをディスパッチします:

bg-dispatch \
  -a claude-code \
  -p "$(cat <<'EOF'
Build a user authentication system with:
- JWT tokens with refresh
- Rate limiting per IP
- Password hashing with bcrypt
- Integration tests
EOF
)" \
  -n "auth-system" \
  -w /path/to/project

ステップ 4:完了を処理する

タスク完了時、エージェントはシステムイベントを受け取ります。一元化されたタスクディレクトリから進行状況を読み取ります(パスはシステムイベントメッセージに含まれます):

cat /path/to/bg-dispatch/data/tasks/<task-id>/progress.md

次にアクション実行:PR を作成、ユーザーに通知、次のタスクをディスパッチします。

ステップ 5:ハートビート統合

エージェントのハートビートで、完了/割り込みされたタスクをチェックします:

node bg-dispatch/task-check.mjs \
  --data-dir bg-dispatch/data \
  --projects-dir /path/to/projects

出力 JSON は注意が必要な内容を示します:

• unnotified — ユーザーに通知されていない完了タスク
• interrupted — 再開が必要なタスク
• stalled — スタックしている可能性があるタスク

監視コマンド(bgd CLI)

bgd CLI はインタラクティブなタスク監視を提供します。バックグラウンドタスクをチェック、ログを表示、タスクライフサイクルを管理します。

タスクをリスト表示

bgd tasks                         # All tasks
bgd tasks --status running        # Only running tasks
bgd tasks --status done           # Only completed tasks
bgd tasks --limit 5               # Limit output

クイックステータス概要

bgd status                        # Summary counts + active task details

タスク詳細を表示

bgd show auth-api                 # Full metadata + progress + git log
bgd show db                       # Partial name match OK

ログを表示

bgd logs auth-api                 # Last 50 lines of output (ANSI stripped)
bgd logs auth-api -n 100          # Last 100 lines
bgd logs auth-api -f              # Follow in real-time
bgd logs auth-api --watchdog      # Watchdog log instead

進行状況を表示

bgd progress auth-api             # Show progress.md from task data

タスクをキャンセル

bgd cancel auth-api               # Kill process tree, update meta, notify

タスクを再開

bgd resume auth-api               # Resume interrupted/killed task

クリーンアップ

bgd clean                         # Remove done/killed tasks older than 24h
bgd clean --all                   # Remove all done/killed tasks
bgd clean --dry-run               # Preview what would be removed

ファイルレイアウト

bg-dispatch/
├── bg-dispatch              # Main dispatcher
├── watchdog.sh              # Stall detection + max runtime
├── notify.sh                # Notification dispatcher
├── task-check.mjs           # Heartbeat integration
├── install.sh               # Setup script
├── bg-dispatch.example.json # Example config
├── SKILL.md                 # This file (OpenClaw Skill)
├── adapters/
│   ├── claude-code.sh       # Claude Code adapter
│   ├── aider.sh             # Aider adapter
│   └── codex.sh             # Codex CLI adapter
├── notifiers/
│   ├── openclaw.sh          # OpenClaw system event notifier
│   ├── webhook.sh           # Generic webhook (Slack/Feishu/Discord)
│   └── command.sh           # Custom command notifier
├── hooks/
│   ├── on-complete.sh       # Claude Code Stop hook
│   └── settings.json        # Hook config
├── docs/
│   └── writing-adapters.md  # Adapter development guide
└── data/tasks/              # Runtime data (gitignored)