jules-dispatch

jules-dispatch 🚀

Google Jules にタスクを並列で一括ディスパッチし、Claude Code や OpenAI Codex CLI 内で MCP ツールとして使用できます。

🌐 言語：英語 · 簡体字中国語

🌐 ランディングページとインタラクティブなドキュメント
https://yuuqq.github.io/jules-dispatch/ — 導入ガイドと MCP 統合の例

---

これは何ですか？

jules-dispatch は、Google Jules API 用の CLI および MCP サーバーで、次のことができます。

• 最大 50 件のセッション作成を同時に実行して、任意の数の Jules タスクをディスパッチできます。実行間隔の調整も可能です
• タイトル、リポジトリ、ブランチ、プロンプトを記述したシンプルな YAML ファイルでタスクを定義できます
• 完了までポーリングし、生成された PR のリンクを収集できます
• 計画を承認したり、フォローアップメッセージを送信したり、暴走したセッションをキャンセルしたり、リアルタイムのアクティビティを追跡したりできます
• MCP サーバーとして Claude Code や Codex に接続できます — AI アシスタントが Jules をツールとして呼び出します

Jules を「一度に 1 件のタスクだけ」のツールから、CLI を使う人間や MCP 経由で操作する他の AI が制御できる 大規模な並列コーディングワーカー群へと変えます。

---

🏗 仕組み

flowchart LR
    O["🧠 Orchestrator<br/>(Claude / Codex / you)"]
    O -->|writes| T["📄 tasks/*.yaml"]
    T --> D["⚡ jules-dispatch batch"]
    D -->|parallel| J1["🤖 Jules #1"]
    D -->|parallel| J2["🤖 Jules #2"]
    D -->|parallel| J3["🤖 Jules #3"]
    D -->|parallel| J4["🤖 Jules #N"]
    J1 --> P1["🔀 PR #1"]
    J2 --> P2["🔀 PR #2"]
    J3 --> P3["🔀 PR #3"]
    J4 --> P4["🔀 PR #N"]

    classDef orch fill:#7c3aed,stroke:#5b21b6,color:#fff
    classDef tool fill:#0891b2,stroke:#0e7490,color:#fff
    classDef worker fill:#f59e0b,stroke:#b45309,color:#fff
    classDef pr fill:#10b981,stroke:#047857,color:#fff
    class O orch
    class D tool
    class J1,J2,J3,J4 worker
    class P1,P2,P3,P4 pr

---

✨ 1.2 の新機能 — オプションの AI タスク計画（LLM は自由に選択）

完全にオプションです。 すべてのコアコマンドは、LLM のキーがなくても動作します。タスクをそのままディスパッチするだけの場合は、このセクションを読み飛ばしてください。

タスク YAML を手作業で書くのはやめましょう。jules-dispatch に 1 文を渡すだけで、LLM がそれを N 件の並列 Jules セッションに展開します。

$ jules-dispatch auto "Migrate every Express route to Fastify and add request-validation tests"

Planning with gpt-4o-mini...

Planned 6 task(s):
  1. Migrate auth routes (/api/auth/*) to Fastify
  2. Migrate user routes (/api/users/*) to Fastify
  3. Migrate billing routes (/api/billing/*) to Fastify
  4. Replace Express middleware with Fastify hooks
  5. Update server bootstrap to use Fastify instance
  6. Add Vitest request-validation tests for all migrated routes

Dispatch all 6 task(s)? [y/N]

好きな LLM を利用できます — OpenAI 互換の /chat/completions エンドポイントであれば、どれでも動作します。

プロバイダー	LLM_BASE_URL	LLM_MODEL の例
OpenAI（デフォルト）	(省略可 — デフォルトは https://api.openai.com/v1)	gpt-4o-mini、gpt-4o、o3-mini
OpenRouter	https://openrouter.ai/api/v1	openrouter/auto、anthropic/claude-opus-4.7
Ollama（ローカル、無料）	http://localhost:11434/v1	llama3.1、qwen2.5-coder:32b
Groq	https://api.groq.com/openai/v1	llama-3.3-70b-versatile
Together / Fireworks / DeepInfra / vLLM / LiteLLM / Azure OpenAI	(各プロバイダーのエンドポイント)	(各プロバイダーのモデル ID)

環境変数（LLM_API_KEY、LLM_BASE_URL、LLM_MODEL）または呼び出しごとのフラグ（--llm-key、--llm-base-url、--llm-model）で設定できます。OPENAI_API_KEY と OPENROUTER_API_KEY もフォールバックとして認識されます。

コマンド / ツール	説明
jules-dispatch plan-tasks "<intent>"	計画のみ — タスクを表示するか、YAML ファイルに書き込みます
jules-dispatch auto "<intent>"	計画とディスパッチをまとめて実行します（確認あり）
MCP jules_plan_tasks	同じタスク計画機能を Claude Code / Codex に公開します (LLM キーが設定されている場合のみ登録されます)
MCP jules_auto	計画とディスパッチをまとめて実行します (LLM キーが設定されている場合のみ登録されます)

---

✨ 1.1 の新機能

• 🧰 MCP サーバー（jules-dispatch mcp）— 常時登録されるツールが 8 個、LLM キーが設定されている場合に使えるオプションの計画ツールが 2 個、オプトイン方式のレガシーエイリアスが 7 個
• 🤖 --json モード — AI エージェントやシェルパイプライン向けに、すべてのコマンドで機械可読な出力を提供します
• ✅ 計画承認ワークフロー — plan、approve コマンドと requirePlanApproval: true タスクオプション
• 📡 リアルタイム追跡 — tail <id> は、アクティビティイベントを発生時にストリーミングします
• ❌ セッションのキャンセル — cancel <id> は、暴走した実行を中止します
• 🔍 直接検索 — get <id> と status --ids は、最近のページに限定されなくなりました
• 🛡️ 実際の失敗検出 — session.state を使用し、迅速に失敗を検出して、明確に異なる終了コードを返します
• ⚡ スマートな再試行 — ジッター付き指数バックオフを使用し、Retry-After を尊重します
• 📥 標準入力からの入力 — dispatch - はパイプから YAML／JSON を読み込みます
• 🔑 --api-key フラグ — 呼び出しごとにキーを渡せるため、.env は不要です

---

✨ 主な機能

機能	詳細
⚡ 上限と間隔を制御したディスパッチ	1～50 個のワーカープールを継続的に補充し、--pace-ms で起動間隔を設定できます
📋 YAML タスクファイル	複数ドキュメントの YAML に対応しています（--- 区切り）
🔄 ステータスのポーリング	PR、計画の承認、失敗を自動検出します
💬 計画とメッセージの制御	計画の承認、フォローアップメッセージの送信、セッションのキャンセルができます
🤖 MCP サーバー	Claude Code または Codex にツールとして追加できます
📦 構造化出力	エージェントやスクリプトへ簡単にパイプできる --json モード
📝 ディスパッチログ	ディスパッチ実行ごとの JSON 監査証跡

---

💡 よくある 5 つのユースケース

変更を独立した PR 規模のタスクに分割できる場合に、jules-dispatch は最も効果を発揮します。タスクが同じファイルを編集する場合や、前の出力に依存する場合は、同時に実行せず、別々のウェーブに分けてディスパッチしてください。

1. 複数のモジュールにテストカバレッジを追加する

認証、課金、ユーザー、監査の各モジュールにテストが必要だとします。専用ディレクトリに、モジュールごとに独立したタスクファイルを 1 つずつ配置し、ディレクトリをバッチとしてディスパッチします。

jules-dispatch batch tasks/add-tests --parallel 4

各 Jules セッションは 1 つのモジュールを担当します。AUTO_CREATE_PR を有効にすると、個別にレビューしてマージできる、対象を絞った PR が作成されます。失敗したタスクは、残りを再起動せずに再試行できます。

役立つ理由： 独立したテスト作業を同時に進められ、大規模でレビューしにくい変更にまとめられることもありません。

2. 大規模な移行を実行可能なタスクに分割する

Express API を Fastify に移行する場合などは、オプションの LLM プランナーを使って、独立したルート、ミドルウェア、起動コード、テスト作業を特定します。

jules-dispatch auto "Migrate the Express API to Fastify and add request-validation tests" \
  --max 8 --parallel 4

auto は提案されたタスクを表示し、ディスパッチ前に確認を求めます。Jules に何かを送信する前に、生成された YAML を保存して編集したい場合は、代わりに plan-tasks を使用します。

役立つ理由： プランナーによって広範な目標を分解するコストを抑えつつ、タスクの境界を明確に保ち、レビュー可能にできます。

3. 複数のリポジトリに同じ変更を展開する

Jules に接続された複数のリポジトリに共通の CI チェック、セキュリティベースライン、またはコントリビューションポリシーを追加するには、各タスクに独自の source を指定します。

title: "Add the security baseline to the API"
prompt: "Add the agreed security checks and open a focused PR."
source: "sources/github/acme/api"
branch: "main"
---
title: "Add the security baseline to the worker"
prompt: "Add the agreed security checks and open a focused PR."
source: "sources/github/acme/worker"
branch: "main"

タスクファイルを専用のバッチディレクトリに配置し、同時実行数と起動間隔を制御してディスパッチします。

jules-dispatch batch tasks/security-baseline --parallel 6 --pace-ms 250

役立つ理由： 1 つのコマンドで展開を調整しながら、リポジトリごとに別々のセッションと PR を維持し、バッチの監査ログも残せます。

4. リスクの高い変更に人間の承認ゲートを設ける

認証、認可、データベース移行では、実装開始前にレビューが必要になることがよくあります。計画後に Jules を停止させるように設定します。

title: "Refactor authorization checks"
prompt: "Centralize API authorization checks without changing the public API."
requirePlanApproval: true

計画を確認し、必要に応じて修正を依頼してから承認し、その後も監視を続けます。

jules-dispatch plan abc123
jules-dispatch message abc123 "Do not change the public API"
jules-dispatch plan abc123       # inspect the revised plan
jules-dispatch approve abc123
jules-dispatch wait abc123

役立つ理由： 委任した実行の利点を活かしながら、影響の大きい決定を自分で管理できます。

5. Claude Code または Codex に実行全体を統括させる

MCP サーバーを設定したら、各セッションを自分で操作するのではなく、望む結果を伝えます。

このリポジトリを分析し、テストの不足箇所を独立したタスクに分割して、Jules に割り当ててください。計画の承認やフィードバックへの回答が必要な場合は、実行前に私に確認してください。すべてのセッションが完了したら、各タスクの結果と PR の URL をまとめてください。

コーディングアシスタントは、jules_dispatch を呼び出してタスクを割り当て、jules_monitor で待機し、対応が必要なセッションを jules_interact で確認して、最終的な PR の概要を返します。

役立つ理由： 目標や重要な判断はあなたが管理し、割り当てやフォローアップ、結果の収集はアシスタントが処理します。

---

🤖 Claude Code または Codex 内で使用する（MCP）

MCP サーバーは、コーディング AI が直接呼び出せる一連のツールとして Jules を公開します。

sequenceDiagram
    autonumber
    actor U as 👤 You
    participant CC as 💬 Claude Code / Codex
    participant MCP as ⚡ jules-dispatch (MCP)
    participant J as ☁️ Google Jules

    U->>CC: "Add tests to 5 modules"
    CC->>MCP: jules_dispatch(tasks)
    MCP->>J: POST /sessions × 5
    J-->>MCP: 5 session IDs
    MCP-->>CC: {dispatched: 5}

    CC->>MCP: jules_monitor(ids, wait=true)
    loop until terminal or action required
        MCP->>J: GET /sessions/{id}
    end
    MCP-->>CC: {sessions, wait: {completed, actionRequired, ...}}

    opt a session requires action
        CC->>MCP: jules_interact(id)
        MCP-->>CC: state + plan + activities
        CC->>MCP: jules_approve_plan(id) or jules_send_message(id, text)
        CC->>MCP: jules_monitor(ids, wait=true)
    end

    CC->>MCP: jules_interact(id)
    MCP-->>CC: terminal status + PR output
    CC-->>U: "Done. PRs: #42, #43, #44, #45, #46"

Claude Code にインストールする

npm install -g @yuuqq/jules-dispatch

セットアップ完全ガイド（GSD との統合を含む）：docs/MCP-INTEGRATION.md

~/.config/claude-code/mcp.json に追加します（または claude mcp add を使用します）。

{
  "mcpServers": {
    "jules-dispatch": {
      "command": "jules-dispatch",
      "args": ["--project", "/path/to/your/project", "mcp"],
      "env": {
        "JULES_API_KEY": "your-api-key-here",
        "JULES_DEFAULT_SOURCE": "sources/github/owner/repo",
        "JULES_DEFAULT_BRANCH": "main"
      }
    }
  }
}

次に Claude Code で、次のように指示します：「auth、payments、users、sessions、audit モジュールにテストを追加する Jules のタスクを 5 件割り当ててください。」 Claude は jules_dispatch を呼び出し、jules_monitor で進捗を監視し、完全なコンテキストや PR の出力が必要な場合は jules_interact を使用します。

OpenAI Codex CLI にインストールする

~/.codex/config.toml に追加します。

[mcp_servers.jules-dispatch]
command = "jules-dispatch"
args = ["--project", "/path/to/your/project", "mcp"]
env = { JULES_API_KEY = "your-api-key-here", JULES_DEFAULT_SOURCE = "sources/github/owner/repo" }

エージェントスキルとしてインストールする

このリポジトリには、skills/jules-dispatch/ に軽量なスキルラッパーも含まれています。このスキルは、Claude Code、Codex、または Agent Skills 互換ホストに対し、jules-dispatch MCP ツールをいつ、どのように使用するかを指示します。

Codex では、フォルダーをコピーするかインストールして、Codex のスキルディレクトリ内で jules-dispatch として配置し、Codex を再起動します。

cp -R skills/jules-dispatch "${CODEX_HOME:-$HOME/.codex}/skills/jules-dispatch"

共有スキルディレクトリを使用する Agent Skills 互換ホストでは、同じフォルダーをそのホストのスキルディレクトリにコピーします。このスキルは指示レイヤーのみを提供します。引き続き jules-dispatch mcp で MCP サーバーを設定し、有効な JULES_API_KEY を用意する必要があります。

公開される MCP ツール

統合ツール（推奨）

サーバーはデフォルトで 8 個のツールを登録します。推奨される統合ツールが 3 個、ユーティリティツールが 5 個です。LLM キーが設定されている場合は、計画用ツールがさらに 2 個登録されます。非推奨のエイリアス 7 個は --legacy-tools / JULES_MCP_LEGACY_TOOLS=1 で利用できますが、デフォルトでは登録されないため、必要になるまではコンテキストを消費しません。

jules_dispatch — 1 つ以上のセッションを作成する

単一のタスクオブジェクト、タスクの配列、または YAML/JSON 文字列を受け付けます。

パラメーター：

パラメーター	型	必須	デフォルト	説明
tasks	object | object[] | string	はい	—	タスク定義。オブジェクトには title と prompt が必要です。文字列は YAML/JSON として解析されます。
format	"yaml" | "json"	いいえ	"yaml"	tasks が文字列の場合の形式
parallel	number	いいえ	10	同時に割り当てる最大数（1–50）
paceMs	number	いいえ	0	セッション作成開始間の全体最小遅延（0–60000 ms）

{
  "tasks": [
    { "title": "Fix auth bug", "prompt": "Fix the null check in login()" },
    { "title": "Add tests", "prompt": "Add unit tests for auth.ts" }
  ],
  "parallel": 5,
  "paceMs": 250
}

割り当てには固定された波状処理ではなく、継続的に補充されるワーカープールを使用します。あるタスクのセッション作成が完了すると、次にキューに入っているタスクを開始できます。paceMs はすべてのワーカーに適用されるため、セッション作成の開始間隔は全体で少なくとも指定時間空きますが、結果の順序はタスクの順序と一致します。

jules_monitor — ステータスを確認するか、次の解決ポイントまで待機する

パラメーター：

パラメーター	型	必須	デフォルト	説明
sessionIds	string[]	はい	—	監視するセッション ID
wait	boolean	いいえ	false	true の場合、すべてのセッションが終了状態になるか、いずれかのセッションで対応が必要になるか、タイムアウトするまでポーリングします
intervalMs	number	いいえ	10000	ポーリング間隔（ミリ秒、最小 1000）
timeoutMs	number	いいえ	600000	最大待機時間（ミリ秒、最小 1000）
failFast	boolean	いいえ	false	最初の失敗時にすぐ終了します

{
  "sessionIds": ["abc123", "def456"],
  "wait": true,
  "timeoutMs": 300000
}

対応が必要な状態は AWAITING_PLAN_APPROVAL、AWAITING_USER_FEEDBACK、PAUSED です。結果に actionRequired が含まれる場合は、jules_interact で該当するセッションを確認し、必要に応じてプランを承認するかフィードバックを送信してから、未解決の ID を指定して再度 jules_monitor を呼び出してください。

jules_interact — セッションの全コンテキストを確認する

セッションの詳細、導出されたステータス、全体で最新のプラン、アクティビティのタイムライン、PR の出力を 1 回の呼び出しで返します。サーバーは、古い順のアクティビティフィード全体をスキャンし、最新の activityCount 件を時系列順で返すとともに、フィード全体の件数を activityTotal として返します。

パラメーター：

パラメーター	型	必須	デフォルト	説明
sessionId	string	はい	—	確認するセッション ID
activityCount	number	いいえ	10	最近のアクティビティの件数（1～100）

{ "sessionId": "abc123", "activityCount": 20 }

ユーティリティツール

ツール	パラメーター	説明
jules_list_sources	(none)	Jules に接続されているすべての GitHub リポジトリを一覧表示します
jules_list_sessions	pageSize?, pageToken?	ページネーション付きで最近のセッションを一覧表示します
jules_approve_plan	sessionId	プラン承認が必要なセッションのプランを承認します
jules_send_message	sessionId, text	フォローアップメッセージを送信します
jules_cancel_session	sessionId	実行中のセッションをキャンセルします

オプションの LLM 搭載ツール（LLM キーが必要）

ツール	パラメーター	説明
jules_plan_tasks	description, maxTasks?, source?, branch?, context?	概要レベルの説明からタスクを計画します
jules_auto	description, maxTasks?, source?, branch?, parallel?, paceMs?	計画とディスパッチを一度に実行します

レスポンス形式

すべてのツールは次を返します：

{ "success": true, "data": { ... } }

エラーは次を返します：

{
  "success": false,
  "error": {
    "message": "Authentication failed",
    "status": 401,
    "name": "Error",
    "recovery_hint": "Check your API key"
  }
}

レガシーツール（非推奨のエイリアス、オプトイン）

jules_dispatch_task、jules_dispatch_batch、jules_get_session、jules_list_activities、jules_get_plan、jules_status、jules_wait_for_completion は互換性のため引き続き機能しますが、デフォルトでは登録されません。次のいずれかで有効にできます：

jules-dispatch mcp --legacy-tools
JULES_MCP_LEGACY_TOOLS=1 jules-dispatch mcp

新しい連携では、統合されたツールを使用してください。

---

🚀 クイックスタート（プレーン CLI）

前提条件

• Node.js 20+
• Google Jules アカウントと API キー
• Jules に接続された GitHub リポジトリ

1. インストール

npm install -g @yuuqq/jules-dispatch

2. セットアップ（対話型ウィザード）

jules-dispatch init

ウィザードでは、API キー、デフォルトのソース、ブランチを入力します。.env ファイルが作成されます。

CI／スクリプト向け（非対話型）：

jules-dispatch init --api-key sk-xxx --source sources/github/owner/repo

3. セットアップを検証する

jules-dispatch doctor

4. タスクを作成する

# tasks/add-dark-mode.yaml
title: "Add Dark Mode Support"
prompt: |
  Add a dark mode toggle to the React app:
  1. Add a ThemeContext with light/dark state
  2. Wrap App with ThemeProvider
  3. Add a toggle button in the Header
  4. Persist preference in localStorage
  5. Open a PR

5. ディスパッチする

jules-dispatch dispatch tasks/add-dark-mode.yaml
# ✓ Add Dark Mode Support
#   Session: https://jules.google.com/session/abc123
#   ID:      abc123

6. ディレクトリ全体を一括ディスパッチする

jules-dispatch batch tasks/ --parallel 10

以上です。インストールから最初の PR まで、6 つのステップで完了します。

---

📖 CLI リファレンス

グローバルフラグ

フラグ	デフォルト	説明
-p, --project <dir>	.	.env ファイルを含むディレクトリ
--api-key <key>		Jules API キー（JULES_API_KEY を上書きします）
--json	off	機械可読形式の出力。ストリーミングコマンドでは NDJSON を使用します。

コマンド

コマンド	説明
init	初回実行時の対話型ウィザード（API キー、ソース、ブランチ）
dispatch <taskFile>	1 つのタスクをディスパッチします。標準入力から読み込むには - を使用します。
batch [taskDir]	ディレクトリ内のすべての .yaml／.yml／.json ファイルをディスパッチします
auto <description>	LLM による計画作成とディスパッチを一度に実行します（確認あり）
plan-tasks <description>	LLM を使用して、意図を N 個のタスク草案に展開します（ディスパッチなし）
status	最近のセッションの概要（または特定の --ids）
get <sessionId>	1 つのセッションの詳細
wait <ids...>	セッションが終了状態になるか、対応が必要になるか、タイムアウトするまでポーリングします
tail <sessionId>	セッションのアクティビティイベントをライブストリーミングします
plan <sessionId>	最新の生成済みプランを表示します
approve <sessionId>	保留中のプランを承認します
message <sessionId> <text>	追加メッセージを送信します
cancel <sessionId>	実行中のセッションをキャンセルします
sources	接続されている GitHub リポジトリを一覧表示します（自動ページネーション）
doctor	環境、API キー、接続、タスクファイルを検証します
mcp	標準入出力経由で MCP サーバーとして実行します

終了コード（シェルスクリプトおよびエージェント向け）

コード	意味
0	成功
1	一般的なエラー
2	認証エラー（API キーがないか、拒否されました）
3	検証または設定エラー（タスクファイル、引数、または Jules の設定に問題があります）
4	部分的な失敗（batch の一部のタスクが失敗しました）
5	タイムアウト（wait が制限時間に達しました）

監視時のエラー動作

status は、セッションまたはアクティビティの検索失敗を status: "error" として明示的に報告し、Jules の失敗を捏造したり、古い可能性のある状態を信頼したりせずに、ゼロ以外の終了コードで終了します。ポーリングコマンドが再試行するのは、ネットワークエラー、レート制限エラー、サーバーエラーのみです。無効なリクエスト、認証エラー、見つからないセッションは直ちに失敗し、エラーのコンテキストには該当するセッション ID が含まれます。

dispatch の例

# Override repo/branch
jules-dispatch dispatch tasks/my-task.yaml \
  --source sources/github/org/other-repo --branch develop

# Read from stdin
echo 'title: Quick fix\nprompt: Fix typo in README' | jules-dispatch dispatch -

# JSON output (great for piping)
jules-dispatch dispatch tasks/my-task.yaml --json | jq -r '.sessionId'

batch の例

jules-dispatch batch tasks/                       # default tasks/ dir
jules-dispatch batch tasks/ --parallel 20         # 20 concurrent
jules-dispatch batch tasks/ --parallel 10 --pace-ms 250  # globally space starts by 250 ms
jules-dispatch batch tasks/ --no-log              # don't write dispatch log
jules-dispatch batch tasks/ --json                # one JSON summary at the end

batch と auto は、どちらも同じ継続的に補充されるワーカープールを使用します。--parallel は同時に作成できるセッション数を制限し、--pace-ms は作成開始間の全体的な最小間隔を設定します。これは各ワーカー内に個別の遅延を追加するものではありません。

wait の例

# Chain dispatch → wait via JSON output:
ID=$(jules-dispatch dispatch tasks/x.yaml --json | jq -r '.sessionId')
jules-dispatch wait "$ID" --interval 10000 --timeout 1800000

tail の例

jules-dispatch tail abc123                        # human-readable stream
jules-dispatch tail abc123 --json                 # NDJSON event stream

---

🔄 セッションのライフサイクル

jules-dispatch はすべての Jules セッションをライフサイクル全体にわたって追跡し、各状態を CLI／MCP 経由で表示します。

stateDiagram-v2
    [*] --> QUEUED
    QUEUED --> PLANNING
    PLANNING --> IN_PROGRESS
    PLANNING --> AWAITING_PLAN_APPROVAL: approval required
    AWAITING_PLAN_APPROVAL --> IN_PROGRESS: approve plan
    IN_PROGRESS --> AWAITING_USER_FEEDBACK: input required
    AWAITING_USER_FEEDBACK --> IN_PROGRESS: send feedback
    IN_PROGRESS --> PAUSED: execution paused
    PAUSED --> IN_PROGRESS: execution resumes
    IN_PROGRESS --> COMPLETED: success
    IN_PROGRESS --> FAILED: error
    COMPLETED --> [*]
    FAILED --> [*]

公式の状態	意味	推奨される操作
STATE_UNSPECIFIED	特定の状態が指定されていません	jules_monitor で再確認するか、jules_interact で調べます
QUEUED／PLANNING／IN_PROGRESS	Jules が処理を進めています	監視を続けます。ライブアクティビティには tail を使用します
AWAITING_PLAN_APPROVAL	生成されたプランの承認が必要です	jules_interact で確認してから、approve／jules_approve_plan を使用します
AWAITING_USER_FEEDBACK	Jules が説明または入力を必要としています	コンテキストを確認してから、message／jules_send_message を使用します
PAUSED	実行が一時停止されており、対応が必要です	コンテキストを確認し、適切であればガイダンスを提供してから、再度監視します
COMPLETED	終了状態：成功	セッションを確認し、PR の出力を取得します
FAILED	終了状態：失敗	最新の失敗アクティビティを確認し、再試行するか、タスクを置き換えるか判断します

互換性を保つため、jules-dispatch は従来の API 状態である PENDING、RUNNING、AWAITING_USER_INPUT、CANCELLED、CANCELED も正規化します。キャンセルには Jules の DELETE /sessions/{id} 操作を使用します。

---

📄 タスクファイル形式

フィールドリファレンス

フィールド	型	必須	デフォルト	説明
title	string	はい	—	CLI のステータスとセッション一覧に表示される、人が読めるタスク名
prompt	string	はい	—	Jules エージェントへの詳細な指示です。具体的であるほど、出力の質が高まります。
source	string	いいえ	.env の JULES_DEFAULT_SOURCE	Jules のソース識別子（例：sources/github/owner/repo）。タスクごとに上書きできます。
branch	string	いいえ	.env の JULES_DEFAULT_BRANCH（または main）	Jules セッションの開始元となる Git ブランチ
autoMode	string	いいえ	AUTO_CREATE_PR	自動化モードです。値：AUTO_CREATE_PR（Jules が PR を自動作成）、NONE
requirePlanApproval	boolean	いいえ	false	true の場合、Jules は計画を生成した後に一時停止し、jules-dispatch approve <id> を待ちます

YAML の例

title: "Add unit tests for auth module"
prompt: |
  Add comprehensive unit tests for src/auth.ts:
  1. Test login with valid credentials
  2. Test login with invalid credentials
  3. Test token refresh flow
  4. Test session expiry handling
  5. Open a PR with the test file
source: "sources/github/myorg/myrepo"
branch: "develop"
autoMode: "AUTO_CREATE_PR"
requirePlanApproval: false

1 つのファイルに複数のタスクを記述する（YAML の --- 区切り）

title: "Fix lint errors in src/auth"
prompt: "Fix all ESLint errors in src/auth.ts"
---
title: "Fix lint errors in src/api"
prompt: "Fix all ESLint errors in src/api.ts"
---
title: "Fix lint errors in src/utils"
prompt: "Fix all ESLint errors in src/utils.ts"

JSON 形式

{
  "title": "Fix the thing",
  "prompt": "Find the bug in src/auth.ts and fix it.",
  "source": "sources/github/owner/repo",
  "branch": "main"
}

JSON 配列（MCP 経由の一括ディスパッチ用）：

[
  { "title": "Task 1", "prompt": "Do thing A" },
  { "title": "Task 2", "prompt": "Do thing B" }
]

---

🤖 AI が指揮する並列開発

代表的なユースケース：jules-dispatch を Claude Code または Codex と組み合わせます。

「Express から Fastify への移行が必要な Node.js バックエンドがあります。コードベースを分析し、作業を独立した移行単位に分割して、jules-dispatch MCP ツールを使ってすべてを並列で Jules にディスパッチしてください。その後、完了するまでポーリングし、PR の URL を報告してください。」

MCP サーバーをインストールすると、アシスタントは次のことを行います。

1. コードベースを分析する
2. 対象ブランチをコミットしてプッシュする。Jules はプッシュされていないローカルの変更ではなく、リモートのソースブランチを基に作業するためです
3. N 個のタスク定義を指定して jules_dispatch を呼び出す
4. wait: true を指定して jules_monitor を呼び出す。対応が必要な場合は、jules_interact で内容を確認して承認またはフィードバックを送信し、再度モニタリングする
5. jules_interact を使ってターミナルのコンテキストと PR の URL を収集する

1 つの戦略的エージェントが指揮する N 個の並列コーディングエージェントを、手を煩わせることなく利用できます。

---

📁 プロジェクト構成

jules-dispatch/
├── src/
│   ├── cli.ts          CLI entry point (Commander)
│   ├── client.ts       Jules REST client (retries, pagination)
│   ├── config.ts       .env + task file loading
│   ├── dispatcher.ts   Task dispatch logic
│   ├── collector.ts    Status polling & wait
│   ├── errors.ts       Structured error translation (Problem/Cause/Fix)
│   ├── output.ts       Text vs JSON output mode, color detection
│   ├── init.ts         Interactive init wizard
│   ├── doctor.ts       Environment validation (doctor command)
│   ├── mcp.ts          MCP server (8 tools + 2 optional planner tools + 7 opt-in aliases)
│   ├── mcp-helpers.ts  MCP response helpers (ok/fail/recovery hints)
│   ├── polling.ts      Shared poll-with-callback engine
│   ├── tail.ts         Bounded, cursor-aware activity tailing
│   ├── planner.ts      Optional LLM task planner
│   ├── log.ts          Verbose logging
│   └── types.ts        TypeScript types
├── tasks/              Your task YAMLs live here
├── .env                Generated by jules-dispatch init
└── .dispatch-logs/     JSON audit trail

---

🛠 開発

npm install
npm run build     # compile TypeScript → dist/
npm run dev       # run CLI directly with tsx
npm run lint
npm run test

---

📜 ライセンス

MIT — LICENSE を参照してください

---

Google Jules を実際にスケールさせるために作られました。