Jules Dispatch

jules-dispatch 🚀

Batch-dispatch tasks to [Google Jules](https://jules.google.com/) in parallel — and use it as an MCP tool inside [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [OpenAI Codex CLI](https://github.com/openai/codex).

🌐 Languages: English · 简体中文

🌐 Landing page & interactive docs

https://yuuqq.github.io/jules-dispatch/ — full onboarding guide and MCP integration examples

---

What Is This?

jules-dispatch is a CLI and an MCP server for the Google Jules API that lets you:

• Dispatch any number of Jules tasks with up to 50 concurrent session creations, optionally paced
• Define tasks as simple YAML files — title, repo, branch, prompt
• Poll for completion and collect generated PR links
• Approve plans, send follow-up messages, cancel runaway sessions, tail live activity
• Plug into Claude Code or Codex as an MCP server — your AI assistant calls Jules as a tool

It turns Jules from a "one task at a time" tool into a massively parallel coding workforce, controlled by either humans on the CLI or other AIs over MCP.

---

🏗 How It Works

flowchart LR

O["🧠 Orchestrator (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

---

✨ What's New in 1.2 — Optional AI Task Planning (BYO LLM)

Entirely optional. All core commands work without any LLM key. Skip this section if you only want raw dispatch.

Stop hand-writing task YAML. Give jules-dispatch one sentence and let an LLM expand it into N parallel Jules sessions.

$ 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]

Bring your own LLM — works with any OpenAI-compatible /chat/completions endpoint:

Configure via env vars (LLM_API_KEY, LLM_BASE_URL, LLM_MODEL) or per-invocation flags (--llm-key, --llm-base-url, --llm-model). OPENAI_API_KEY and OPENROUTER_API_KEY are also recognised as fallbacks.

---

✨ What's New in 1.1

• 🧰 MCP server (jules-dispatch mcp) — 8 always-registered tools, plus 2 optional planning tools when an LLM key is configured, and 7 opt-in legacy aliases
• 🤖 `--json` mode — machine-readable output on every command for AI agents and shell pipelines
• ✅ Plan approval workflow — plan, approve commands + requirePlanApproval: true task option
• 📡 Live tailing — tail streams activity events as they happen
• ❌ Cancel sessions — cancel aborts runaway runs
• 🔍 Direct lookup — get , status --ids no longer limited to the recent page
• 🛡️ Real failure detection — uses session.state, fails fast, distinct exit codes
• ⚡ Smart retries — exponential backoff with jitter, honours Retry-After
• 📥 Stdin input — dispatch - reads YAML/JSON from a pipe
• 🔑 `--api-key` flag — pass keys per-invocation, no .env required

---

✨ Key Features

---

💡 Five Common Use Cases

jules-dispatch works best when a change can be split into independent, PR-sized tasks. If tasks edit the same files or depend on earlier output, dispatch them in separate waves instead of running them concurrently.

1. Add test coverage across several modules

Suppose the auth, billing, users, and audit modules all need tests. Put one self-contained task file per module in a dedicated directory, then dispatch the directory as a batch:

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

Each Jules session owns one module. With AUTO_CREATE_PR enabled, the result is a set of focused PRs that can be reviewed and merged independently. A failed task can be retried without restarting the rest.

Why it helps: independent test work runs at the same time without turning into one large, hard-to-review change.

2. Break a large migration into executable tasks

For a goal such as migrating an Express API to Fastify, use the optional LLM planner to identify independent routes, middleware, startup code, and test work:

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

--max 8 --parallel 4

auto shows the proposed tasks and asks for confirmation before dispatching them. Use plan-tasks instead when you want to save and edit the generated YAML before anything is sent to Jules.

Why it helps: the planner reduces the cost of decomposing a broad goal while keeping the task boundaries visible and reviewable.

3. Roll out the same change across multiple repositories

To add a shared CI check, security baseline, or contribution policy across several Jules-connected repositories, give each task its own 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"

Place the task file in a dedicated batch directory and dispatch it with controlled concurrency and launch pacing:

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

Why it helps: one command coordinates the rollout while preserving a separate session and PR for each repository plus an audit log for the batch.

4. Keep a human approval gate for risky changes

Authentication, authorization, and database migrations often need review before implementation begins. Require Jules to stop after planning:

title: "Refactor authorization checks"

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

Inspect the plan, send corrections if needed, approve it, and then continue monitoring:

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

Why it helps: you keep control of high-impact decisions without giving up delegated execution.

5. Let Claude Code or Codex orchestrate the whole run

After configuring the MCP server, describe the outcome instead of operating each session yourself:

Analyze this repository, split its test gaps into independent tasks, and dispatch them to Jules. Ask me before approving plans or answering feedback requests. When every session finishes, summarize the outcome and PR URL for each task.

The coding assistant can call jules_dispatch, wait with jules_monitor, inspect action-required sessions with jules_interact, and return a final PR summary.

Why it helps: you manage the goal and the important decisions while the assistant handles dispatch, follow-up, and result collection.

---

🤖 Use Inside Claude Code or Codex (MCP)

The MCP server exposes Jules as a set of tools your coding AI can call directly.

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"

Install for Claude Code

npm install -g @yuuqq/jules-dispatch

Full setup guide (including GSD integration): docs/MCP-INTEGRATION.md

Add to ~/.config/claude-code/mcp.json (or use 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" } } } }