{
"markdown": "# jules-dispatch ๐\n\n> **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).**\n\n[](https://www.npmjs.com/package/@yuuqq/jules-dispatch)\n[](https://github.com/Yuuqq/jules-dispatch/actions/workflows/ci.yml)\n[](https://www.typescriptlang.org/)\n[](https://modelcontextprotocol.io/)\n[](LICENSE)\n\n๐ **Languages**: **English** ยท [็ฎไฝไธญๆ](README.zh-CN.md)\n\n
\n \n
\n\n> **๐ Landing page & interactive docs** \n> [https://yuuqq.github.io/jules-dispatch/](https://yuuqq.github.io/jules-dispatch/) โ full onboarding guide and MCP integration examples\n\n---\n\n## What Is This?\n\n**jules-dispatch** is a CLI **and** an [MCP server](https://modelcontextprotocol.io/) for the [Google Jules API](https://jules.google.com/) that lets you:\n\n- Dispatch any number of Jules tasks with up to **50 concurrent session creations**, optionally paced\n- Define tasks as simple **YAML files** โ title, repo, branch, prompt\n- **Poll for completion** and collect generated PR links\n- Approve plans, send follow-up messages, cancel runaway sessions, tail live activity\n- Plug into **Claude Code** or **Codex** as an MCP server โ your AI assistant calls Jules as a tool\n\nIt 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.\n\n---\n\n## ๐ How It Works\n\n```mermaid\nflowchart LR\n O[\"๐ง Orchestrator (Claude / Codex / you)\"]\n O -->|writes| T[\"๐ tasks/*.yaml\"]\n T --> D[\"โก jules-dispatch batch\"]\n D -->|parallel| J1[\"๐ค Jules #1\"]\n D -->|parallel| J2[\"๐ค Jules #2\"]\n D -->|parallel| J3[\"๐ค Jules #3\"]\n D -->|parallel| J4[\"๐ค Jules #N\"]\n J1 --> P1[\"๐ PR #1\"]\n J2 --> P2[\"๐ PR #2\"]\n J3 --> P3[\"๐ PR #3\"]\n J4 --> P4[\"๐ PR #N\"]\n\n classDef orch fill:#7c3aed,stroke:#5b21b6,color:#fff\n classDef tool fill:#0891b2,stroke:#0e7490,color:#fff\n classDef worker fill:#f59e0b,stroke:#b45309,color:#fff\n classDef pr fill:#10b981,stroke:#047857,color:#fff\n class O orch\n class D tool\n class J1,J2,J3,J4 worker\n class P1,P2,P3,P4 pr\n```\n\n---\n\n## โจ What's New in 1.2 โ Optional AI Task Planning (BYO LLM)\n\n> **Entirely optional.** All core commands work without any LLM key. Skip this section if you only want raw dispatch.\n\nStop hand-writing task YAML. Give jules-dispatch **one sentence** and let an LLM expand it into N parallel Jules sessions.\n\n```bash\n$ jules-dispatch auto \"Migrate every Express route to Fastify and add request-validation tests\"\n\nPlanning with gpt-4o-mini...\n\nPlanned 6 task(s):\n 1. Migrate auth routes (/api/auth/*) to Fastify\n 2. Migrate user routes (/api/users/*) to Fastify\n 3. Migrate billing routes (/api/billing/*) to Fastify\n 4. Replace Express middleware with Fastify hooks\n 5. Update server bootstrap to use Fastify instance\n 6. Add Vitest request-validation tests for all migrated routes\n\nDispatch all 6 task(s)? [y/N]\n```\n\n**Bring your own LLM** โ works with any OpenAI-compatible `/chat/completions` endpoint:\n\n| Provider | `LLM_BASE_URL` | Example `LLM_MODEL` |\n|---|---|---|\n| **OpenAI** (default) | *(omit โ defaults to `https://api.openai.com/v1`)* | `gpt-4o-mini`, `gpt-4o`, `o3-mini` |\n| **OpenRouter** | `https://openrouter.ai/api/v1` | `openrouter/auto`, `anthropic/claude-opus-4.7` |\n| **Ollama** (local, free) | `http://localhost:11434/v1` | `llama3.1`, `qwen2.5-coder:32b` |\n| **Groq** | `https://api.groq.com/openai/v1` | `llama-3.3-70b-versatile` |\n| **Together / Fireworks / DeepInfra / vLLM / LiteLLM / Azure OpenAI** | *(their endpoint)* | *(their model id)* |\n\nConfigure 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.\n\n| Command / Tool | What it does |\n|---|---|\n| `jules-dispatch plan-tasks \"\"` | Plan only โ print or write tasks to a YAML file |\n| `jules-dispatch auto \"\"` | Plan + dispatch in one shot (with confirmation) |\n| MCP `jules_plan_tasks` | Same planning, exposed to Claude Code / Codex *(only registered if an LLM key is configured)* |\n| MCP `jules_auto` | One-shot plan + dispatch *(only registered if an LLM key is configured)* |\n\n---\n\n## โจ What's New in 1.1\n\n- ๐งฐ **MCP server** (`jules-dispatch mcp`) โ 15 always-registered tools, plus 2 optional planning tools when an LLM key is configured\n- ๐ค **`--json` mode** โ machine-readable output on every command for AI agents and shell pipelines\n- โ **Plan approval workflow** โ `plan`, `approve` commands + `requirePlanApproval: true` task option\n- ๐ก **Live tailing** โ `tail ` streams activity events as they happen\n- โ **Cancel sessions** โ `cancel ` aborts runaway runs\n- ๐ **Direct lookup** โ `get `, `status --ids` no longer limited to the recent page\n- ๐ก๏ธ **Real failure detection** โ uses session.state, fails fast, distinct exit codes\n- โก **Smart retries** โ exponential backoff with jitter, honours `Retry-After`\n- ๐ฅ **Stdin input** โ `dispatch -` reads YAML/JSON from a pipe\n- ๐ **`--api-key` flag** โ pass keys per-invocation, no .env required\n\n---\n\n## โจ Key Features\n\n| Feature | Details |\n|---|---|\n| โก Bounded, paced dispatch | Continuously replenish a 1โ50 worker pool and optionally space launches with `--pace-ms` |\n| ๐ YAML task files | Multi-document YAML supported (`---` separators) |\n| ๐ Status polling | Auto-detects PRs, plan approvals, failures |\n| ๐ฌ Plan & message control | Approve plans, send follow-up messages, cancel sessions |\n| ๐ค MCP server | Drop into Claude Code or Codex as a tool |\n| ๐ฆ Structured output | `--json` mode for clean piping into agents and scripts |\n| ๐ Dispatch logs | JSON audit trail of every dispatch run |\n\n---\n\n## ๐ก Five Common Use Cases\n\n`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.\n\n### 1. Add test coverage across several modules\n\nSuppose 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:\n\n```bash\njules-dispatch batch tasks/add-tests --parallel 4\n```\n\nEach 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.\n\n**Why it helps:** independent test work runs at the same time without turning into one large, hard-to-review change.\n\n### 2. Break a large migration into executable tasks\n\nFor 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:\n\n```bash\njules-dispatch auto \"Migrate the Express API to Fastify and add request-validation tests\" \\\n --max 8 --parallel 4\n```\n\n`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.\n\n**Why it helps:** the planner reduces the cost of decomposing a broad goal while keeping the task boundaries visible and reviewable.\n\n### 3. Roll out the same change across multiple repositories\n\nTo add a shared CI check, security baseline, or contribution policy across several Jules-connected repositories, give each task its own `source`:\n\n```yaml\ntitle: \"Add the security baseline to the API\"\nprompt: \"Add the agreed security checks and open a focused PR.\"\nsource: \"sources/github/acme/api\"\nbranch: \"main\"\n---\ntitle: \"Add the security baseline to the worker\"\nprompt: \"Add the agreed security checks and open a focused PR.\"\nsource: \"sources/github/acme/worker\"\nbranch: \"main\"\n```\n\nPlace the task file in a dedicated batch directory and dispatch it with controlled concurrency and launch pacing:\n\n```bash\njules-dispatch batch tasks/security-baseline --parallel 6 --pace-ms 250\n```\n\n**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.\n\n### 4. Keep a human approval gate for risky changes\n\nAuthentication, authorization, and database migrations often need review before implementation begins. Require Jules to stop after planning:\n\n```yaml\ntitle: \"Refactor authorization checks\"\nprompt: \"Centralize API authorization checks without changing the public API.\"\nrequirePlanApproval: true\n```\n\nInspect the plan, send corrections if needed, approve it, and then continue monitoring:\n\n```bash\njules-dispatch plan abc123\njules-dispatch message abc123 \"Do not change the public API\"\njules-dispatch plan abc123 # inspect the revised plan\njules-dispatch approve abc123\njules-dispatch wait abc123\n```\n\n**Why it helps:** you keep control of high-impact decisions without giving up delegated execution.\n\n### 5. Let Claude Code or Codex orchestrate the whole run\n\nAfter configuring the MCP server, describe the outcome instead of operating each session yourself:\n\n> 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.\n\nThe coding assistant can call `jules_dispatch`, wait with `jules_monitor`, inspect action-required sessions with `jules_interact`, and return a final PR summary.\n\n**Why it helps:** you manage the goal and the important decisions while the assistant handles dispatch, follow-up, and result collection.\n\n---\n\n## ๐ค Use Inside Claude Code or Codex (MCP)\n\nThe MCP server exposes Jules as a set of tools your coding AI can call directly.\n\n```mermaid\nsequenceDiagram\n autonumber\n actor U as ๐ค You\n participant CC as ๐ฌ Claude Code / Codex\n participant MCP as โก jules-dispatch (MCP)\n participant J as โ๏ธ Google Jules\n\n U->>CC: \"Add tests to 5 modules\"\n CC->>MCP: jules_dispatch(tasks)\n MCP->>J: POST /sessions ร 5\n J-->>MCP: 5 session IDs\n MCP-->>CC: {dispatched: 5}\n\n CC->>MCP: jules_monitor(ids, wait=true)\n loop until terminal or action required\n MCP->>J: GET /sessions/{id}\n end\n MCP-->>CC: {sessions, wait: {completed, actionRequired, ...}}\n\n opt a session requires action\n CC->>MCP: jules_interact(id)\n MCP-->>CC: state + plan + activities\n CC->>MCP: jules_approve_plan(id) or jules_send_message(id, text)\n CC->>MCP: jules_monitor(ids, wait=true)\n end\n\n CC->>MCP: jules_interact(id)\n MCP-->>CC: terminal status + PR output\n CC-->>U: \"Done. PRs: #42, #43, #44, #45, #46\"\n```\n\n### Install for Claude Code\n\n```bash\nnpm install -g @yuuqq/jules-dispatch\n```\n\n> **Full setup guide** (including GSD integration): [docs/MCP-INTEGRATION.md](docs/MCP-INTEGRATION.md)\n\nAdd to `~/.config/claude-code/mcp.json` (or use `claude mcp add`):\n\n```json\n{\n \"mcpServers\": {\n \"jules-dispatch\": {\n \"command\": \"jules-dispatch\",\n \"args\": [\"--project\", \"/path/to/your/project\", \"mcp\"],\n \"env\": {\n \"JULES_API_KEY\": \"your-api-key-here\",\n \"JULES_DEFAULT_SOURCE\": \"sources/github/owner/repo\",\n \"JULES_DEFAULT_BRANCH\": \"main\"\n }\n }\n }\n}\n```\n\nThen in Claude Code: *\"Dispatch 5 Jules tasks to add tests to the auth, payments, users, sessions, and audit modules.\"* Claude calls `jules_dispatch`, monitors them with `jules_monitor`, and uses `jules_interact` when it needs full context or PR output.\n\n### Install for OpenAI Codex CLI\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.jules-dispatch]\ncommand = \"jules-dispatch\"\nargs = [\"--project\", \"/path/to/your/project\", \"mcp\"]\nenv = { JULES_API_KEY = \"your-api-key-here\", JULES_DEFAULT_SOURCE = \"sources/github/owner/repo\" }\n```\n\n### Install as an Agent Skill\n\nThis repository also ships a lightweight skill wrapper at `skills/jules-dispatch/`. The skill teaches Claude Code, Codex, or any Agent Skills-compatible host when and how to use the `jules-dispatch` MCP tools.\n\nFor Codex, copy or install the folder as `jules-dispatch` in your Codex skills directory, then restart Codex:\n\n```bash\ncp -R skills/jules-dispatch \"${CODEX_HOME:-$HOME/.codex}/skills/jules-dispatch\"\n```\n\nFor Agent Skills-compatible hosts that use a shared skills directory, copy the same folder into that host's skills directory. The skill is only the instruction layer; you still need the MCP server configured with `jules-dispatch mcp` and a valid `JULES_API_KEY`.\n\n### MCP Tools Exposed\n\n#### Consolidated tools (recommended)\n\nThe server always registers 15 tools: 3 recommended consolidated tools, 5 utility tools, and 7 deprecated aliases. Two additional planning tools are registered when an LLM key is configured.\n\n##### `jules_dispatch` โ Create one or more sessions\n\nAccepts a single task object, an array of tasks, or a YAML/JSON string.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `tasks` | `object \\| object[] \\| string` | **Yes** | โ | Task definition(s). Objects need `title` + `prompt`. Strings are parsed as YAML/JSON. |\n| `format` | `\"yaml\" \\| \"json\"` | No | `\"yaml\"` | Format when `tasks` is a string |\n| `parallel` | `number` | No | `10` | Max concurrent dispatches (1โ50) |\n| `paceMs` | `number` | No | `0` | Global minimum delay between session creation starts (0โ60000 ms) |\n\n```json\n{\n \"tasks\": [\n { \"title\": \"Fix auth bug\", \"prompt\": \"Fix the null check in login()\" },\n { \"title\": \"Add tests\", \"prompt\": \"Add unit tests for auth.ts\" }\n ],\n \"parallel\": 5,\n \"paceMs\": 250\n}\n```\n\nDispatch uses a continuously replenished worker pool rather than fixed waves: whenever one task finishes creating its session, the next queued task can start. `paceMs` applies globally across all workers, so consecutive creation starts are separated by at least that interval while result order still matches task order.\n\n##### `jules_monitor` โ Check status or wait for the next resolution point\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `sessionIds` | `string[]` | **Yes** | โ | Session IDs to monitor |\n| `wait` | `boolean` | No | `false` | If true, poll until all sessions are terminal, any session requires action, or the timeout expires |\n| `intervalMs` | `number` | No | `10000` | Poll interval in ms (min 1000) |\n| `timeoutMs` | `number` | No | `600000` | Max wait time in ms (min 1000) |\n| `failFast` | `boolean` | No | `false` | Exit immediately on first failure |\n\n```json\n{\n \"sessionIds\": [\"abc123\", \"def456\"],\n \"wait\": true,\n \"timeoutMs\": 300000\n}\n```\n\nAction-required states are `AWAITING_PLAN_APPROVAL`, `AWAITING_USER_FEEDBACK`, and `PAUSED`. When the result includes `actionRequired`, inspect those sessions with `jules_interact`, approve the plan or send feedback as appropriate, then call `jules_monitor` again for the unresolved IDs.\n\n##### `jules_interact` โ Inspect a session in full context\n\nReturns session details, derived status, the globally latest plan, activity timeline, and PR output in one call. The server scans the complete oldest-first activity feed, then returns the newest `activityCount` entries in chronological order plus `activityTotal` for the full feed.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `sessionId` | `string` | **Yes** | โ | Session ID to inspect |\n| `activityCount` | `number` | No | `10` | Number of recent activities (1โ100) |\n\n```json\n{ \"sessionId\": \"abc123\", \"activityCount\": 20 }\n```\n\n#### Utility tools\n\n| Tool | Parameters | Description |\n|---|---|---|\n| `jules_list_sources` | *(none)* | List all GitHub repos connected to Jules |\n| `jules_list_sessions` | `pageSize?`, `pageToken?` | List recent sessions with pagination |\n| `jules_approve_plan` | `sessionId` | Approve a plan-gated session |\n| `jules_send_message` | `sessionId`, `text` | Send a follow-up message |\n| `jules_cancel_session` | `sessionId` | Cancel a running session |\n\n#### Optional LLM-powered tools (requires LLM key)\n\n| Tool | Parameters | Description |\n|---|---|---|\n| `jules_plan_tasks` | `description`, `maxTasks?`, `source?`, `branch?`, `context?` | Plan tasks from a high-level description |\n| `jules_auto` | `description`, `maxTasks?`, `source?`, `branch?`, `parallel?`, `paceMs?` | Plan + dispatch in one shot |\n\n#### Response format\n\nAll tools return:\n```json\n{ \"success\": true, \"data\": { ... } }\n```\n\nErrors return:\n```json\n{\n \"success\": false,\n \"error\": {\n \"message\": \"Authentication failed\",\n \"status\": 401,\n \"name\": \"Error\",\n \"recovery_hint\": \"Check your API key\"\n }\n}\n```\n\n#### Legacy tools (deprecated aliases)\n\n`jules_dispatch_task`, `jules_dispatch_batch`, `jules_get_session`, `jules_list_activities`, `jules_get_plan`, `jules_status`, and `jules_wait_for_completion` remain functional for compatibility. New integrations should use the consolidated tools.\n\n---\n\n## ๐ Quick Start (Plain CLI)\n\n### Prerequisites\n\n- Node.js 20+\n- A [Google Jules](https://jules.google.com/) account and API key\n- A GitHub repository connected to Jules\n\n### 1. Install\n\n```bash\nnpm install -g @yuuqq/jules-dispatch\n```\n\n### 2. Set up (interactive wizard)\n\n```bash\njules-dispatch init\n```\n\nThe wizard prompts for your API key, default source, and branch. It writes a `.env` file.\n\nFor CI/scripts (non-interactive):\n```bash\njules-dispatch init --api-key sk-xxx --source sources/github/owner/repo\n```\n\n### 3. Validate your setup\n\n```bash\njules-dispatch doctor\n```\n\n### 4. Write a task\n\n```yaml\n# tasks/add-dark-mode.yaml\ntitle: \"Add Dark Mode Support\"\nprompt: |\n Add a dark mode toggle to the React app:\n 1. Add a ThemeContext with light/dark state\n 2. Wrap App with ThemeProvider\n 3. Add a toggle button in the Header\n 4. Persist preference in localStorage\n 5. Open a PR\n```\n\n### 5. Dispatch it\n\n```bash\njules-dispatch dispatch tasks/add-dark-mode.yaml\n# โ Add Dark Mode Support\n# Session: https://jules.google.com/session/abc123\n# ID: abc123\n```\n\n### 6. Batch-dispatch a whole directory\n\n```bash\njules-dispatch batch tasks/ --parallel 10\n```\n\nThat's it โ 6 steps from install to your first PR.\n\n---\n\n## ๐ CLI Reference\n\n### Global flags\n\n| Flag | Default | Description |\n|---|---|---|\n| `-p, --project ` | `.` | Directory containing your `.env` file |\n| `--api-key ` | | Jules API key (overrides `JULES_API_KEY`) |\n| `--json` | off | Machine-readable output. NDJSON for streaming commands. |\n\n### Commands\n\n| Command | What it does |\n|---|---|\n| `init` | Interactive first-run wizard (API key, source, branch) |\n| `dispatch ` | Dispatch a single task. Use `-` to read from stdin. |\n| `batch [taskDir]` | Dispatch all `.yaml`/`.yml`/`.json` files in a directory |\n| `auto ` | LLM-plan + dispatch in one shot (with confirmation) |\n| `plan-tasks ` | Use LLM to expand an intent into N task drafts (no dispatch) |\n| `status` | Summary of recent sessions (or specific `--ids`) |\n| `get ` | Full details of one session |\n| `wait ` | Poll until sessions are terminal, require action, or time out |\n| `tail ` | Live-stream activity events for a session |\n| `plan ` | Show the most recent generated plan |\n| `approve ` | Approve a pending plan |\n| `message ` | Send a follow-up message |\n| `cancel ` | Cancel a running session |\n| `sources` | List connected GitHub repos (auto-paginates) |\n| `doctor` | Validate environment, API key, connectivity, task files |\n| `mcp` | Run as an MCP server over stdio |\n\n### Exit codes (for shell scripts and agents)\n\n| Code | Meaning |\n|---|---|\n| `0` | Success |\n| `1` | Generic error |\n| `2` | Authentication error (missing or rejected API key) |\n| `3` | Validation or configuration error (bad task file, args, or Jules settings) |\n| `4` | Partial failure (some `batch` tasks failed) |\n| `5` | Timeout (`wait` ran out of time) |\n\n### Monitoring error behavior\n\n`status` reports session or activity lookup failures explicitly as `status: \"error\"` and exits nonzero instead of fabricating a Jules failure or trusting a potentially stale state. Polling commands retry only network, rate-limit, and server errors; invalid requests, authentication failures, and missing sessions fail immediately with the affected session ID in the error context.\n\n### `dispatch` examples\n\n```bash\n# Override repo/branch\njules-dispatch dispatch tasks/my-task.yaml \\\n --source sources/github/org/other-repo --branch develop\n\n# Read from stdin\necho 'title: Quick fix\\nprompt: Fix typo in README' | jules-dispatch dispatch -\n\n# JSON output (great for piping)\njules-dispatch dispatch tasks/my-task.yaml --json | jq -r '.sessionId'\n```\n\n### `batch` examples\n\n```bash\njules-dispatch batch tasks/ # default tasks/ dir\njules-dispatch batch tasks/ --parallel 20 # 20 concurrent\njules-dispatch batch tasks/ --parallel 10 --pace-ms 250 # globally space starts by 250 ms\njules-dispatch batch tasks/ --no-log # don't write dispatch log\njules-dispatch batch tasks/ --json # one JSON summary at the end\n```\n\n`batch` and `auto` both use the same continuously replenished worker pool. `--parallel` caps in-flight session creation and `--pace-ms` sets the global minimum spacing between creation starts; it does not add a delay separately inside each worker.\n\n### `wait` example\n\n```bash\n# Chain dispatch โ wait via JSON output:\nID=$(jules-dispatch dispatch tasks/x.yaml --json | jq -r '.sessionId')\njules-dispatch wait \"$ID\" --interval 10000 --timeout 1800000\n```\n\n### `tail` example\n\n```bash\njules-dispatch tail abc123 # human-readable stream\njules-dispatch tail abc123 --json # NDJSON event stream\n```\n\n---\n\n## ๐ Session Lifecycle\n\njules-dispatch tracks every Jules session through its full lifecycle and surfaces each state through the CLI / MCP:\n\n```mermaid\nstateDiagram-v2\n [*] --> QUEUED\n QUEUED --> PLANNING\n PLANNING --> IN_PROGRESS\n PLANNING --> AWAITING_PLAN_APPROVAL: approval required\n AWAITING_PLAN_APPROVAL --> IN_PROGRESS: approve plan\n IN_PROGRESS --> AWAITING_USER_FEEDBACK: input required\n AWAITING_USER_FEEDBACK --> IN_PROGRESS: send feedback\n IN_PROGRESS --> PAUSED: execution paused\n PAUSED --> IN_PROGRESS: execution resumes\n IN_PROGRESS --> COMPLETED: success\n IN_PROGRESS --> FAILED: error\n COMPLETED --> [*]\n FAILED --> [*]\n```\n\n| Official state | Meaning | Recommended action |\n|---|---|---|\n| `STATE_UNSPECIFIED` | No specific state was supplied | Recheck with `jules_monitor` or inspect with `jules_interact` |\n| `QUEUED` / `PLANNING` / `IN_PROGRESS` | Jules is actively progressing | Continue monitoring; use `tail` for live activity |\n| `AWAITING_PLAN_APPROVAL` | The generated plan needs approval | Review with `jules_interact`, then use `approve` / `jules_approve_plan` |\n| `AWAITING_USER_FEEDBACK` | Jules needs clarification or input | Inspect context, then use `message` / `jules_send_message` |\n| `PAUSED` | Execution is paused and needs attention | Inspect context, provide guidance if appropriate, then monitor again |\n| `COMPLETED` | Terminal success | Inspect the session and collect PR output |\n| `FAILED` | Terminal failure | Inspect the newest failure activity and decide whether to retry or replace the task |\n\nFor compatibility, jules-dispatch also normalizes legacy API states: `PENDING`, `RUNNING`, `AWAITING_USER_INPUT`, `CANCELLED`, and `CANCELED`. Cancellation is sent with the Jules `DELETE /sessions/{id}` operation.\n\n---\n\n## ๐ Task File Format\n\n### Field Reference\n\n| Field | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `title` | `string` | **Yes** | โ | Human-readable task name shown in CLI status and session lists |\n| `prompt` | `string` | **Yes** | โ | Detailed instructions for the Jules agent. The more specific, the better the output. |\n| `source` | `string` | No | `JULES_DEFAULT_SOURCE` from `.env` | Jules source identifier, e.g. `sources/github/owner/repo`. Override per-task. |\n| `branch` | `string` | No | `JULES_DEFAULT_BRANCH` from `.env` (or `main`) | Git branch for the Jules session to start from |\n| `autoMode` | `string` | No | `AUTO_CREATE_PR` | Automation mode. Values: `AUTO_CREATE_PR` (Jules creates a PR automatically), `NONE` |\n| `requirePlanApproval` | `boolean` | No | `false` | When `true`, Jules pauses after generating a plan and waits for `jules-dispatch approve ` |\n\n### YAML example\n\n```yaml\ntitle: \"Add unit tests for auth module\"\nprompt: |\n Add comprehensive unit tests for src/auth.ts:\n 1. Test login with valid credentials\n 2. Test login with invalid credentials\n 3. Test token refresh flow\n 4. Test session expiry handling\n 5. Open a PR with the test file\nsource: \"sources/github/myorg/myrepo\"\nbranch: \"develop\"\nautoMode: \"AUTO_CREATE_PR\"\nrequirePlanApproval: false\n```\n\n### Multiple tasks in one file (YAML `---` separators)\n\n```yaml\ntitle: \"Fix lint errors in src/auth\"\nprompt: \"Fix all ESLint errors in src/auth.ts\"\n---\ntitle: \"Fix lint errors in src/api\"\nprompt: \"Fix all ESLint errors in src/api.ts\"\n---\ntitle: \"Fix lint errors in src/utils\"\nprompt: \"Fix all ESLint errors in src/utils.ts\"\n```\n\n### JSON format\n\n```json\n{\n \"title\": \"Fix the thing\",\n \"prompt\": \"Find the bug in src/auth.ts and fix it.\",\n \"source\": \"sources/github/owner/repo\",\n \"branch\": \"main\"\n}\n```\n\nJSON array (for batch dispatch via MCP):\n\n```json\n[\n { \"title\": \"Task 1\", \"prompt\": \"Do thing A\" },\n { \"title\": \"Task 2\", \"prompt\": \"Do thing B\" }\n]\n```\n\n---\n\n## ๐ค AI-Orchestrated Parallel Development\n\nThe killer use case: combine jules-dispatch with **Claude Code** or **Codex**.\n\n> *\"I have a Node.js backend that needs to be migrated from Express to Fastify. Analyse the codebase, split the work into independent migration units, and dispatch them all to Jules in parallel using the jules-dispatch MCP tools. Then poll for completion and report back the PR URLs.\"*\n\nWith the MCP server installed, your assistant will:\n\n1. Analyse your codebase\n2. Commit and push the target branch, because Jules works from the remote source branch rather than unpushed local changes\n3. Call `jules_dispatch` with N task definitions\n4. Call `jules_monitor` with `wait: true`; if action is required, inspect with `jules_interact`, approve or send feedback, and monitor again\n5. Use `jules_interact` to collect terminal context and PR URLs\n\nYou get **N parallel coding agents** orchestrated by **one strategic agent**, hands-free.\n\n---\n\n## ๐ Project Structure\n\n```\njules-dispatch/\nโโโ src/\nโ โโโ cli.ts CLI entry point (Commander)\nโ โโโ client.ts Jules REST client (retries, pagination)\nโ โโโ config.ts .env + task file loading\nโ โโโ dispatcher.ts Task dispatch logic\nโ โโโ collector.ts Status polling & wait\nโ โโโ errors.ts Structured error translation (Problem/Cause/Fix)\nโ โโโ output.ts Text vs JSON output mode, color detection\nโ โโโ init.ts Interactive init wizard\nโ โโโ doctor.ts Environment validation (doctor command)\nโ โโโ mcp.ts MCP server (15 tools + 2 optional planner tools)\nโ โโโ mcp-helpers.ts MCP response helpers (ok/fail/recovery hints)\nโ โโโ polling.ts Shared poll-with-callback engine\nโ โโโ tail.ts Bounded, cursor-aware activity tailing\nโ โโโ planner.ts Optional LLM task planner\nโ โโโ log.ts Verbose logging\nโ โโโ types.ts TypeScript types\nโโโ tasks/ Your task YAMLs live here\nโโโ .env Generated by jules-dispatch init\nโโโ .dispatch-logs/ JSON audit trail\n```\n\n---\n\n## ๐ Development\n\n```bash\nnpm install\nnpm run build # compile TypeScript โ dist/\nnpm run dev # run CLI directly with tsx\nnpm run lint\nnpm run test\n```\n\n---\n\n## ๐ License\n\nMIT โ see [LICENSE](LICENSE)\n\n---\n\n*Built to make [Google Jules](https://jules.google.com/) actually scale.*\n",
"bytes": 28685,
"sha": "6489c746893b57e39664e8f70434d41a0cb5649ba4dac66e5c361dacefaf42ed",
"repo_slug": "yuuqq/jules-dispatch",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_yuuqq_jules_dispatch_24e588e2/readme"
}
![\"jules-dispatch](\"docs/banner.png\")
\n