Dispatch

AI agent orchestration CLI — parse work items from GitHub Issues, Azure DevOps, or local markdown files, dispatch each unit of work to a coding agent (OpenCode, GitHub Copilot, Claude Code, or OpenAI Codex), and commit results with conventional commits.

What it does

Dispatch closes the gap between issue trackers and AI coding agents. It:

1. Fetches work items from GitHub Issues, Azure DevOps Work Items, or local markdown specs.
2. Generates structured specs via an AI agent that explores the codebase and produces task lists.
3. Plans and executes each task in isolated AI sessions, with an optional two-phase planner-then-executor pipeline.
4. Manages the git lifecycle — branching, committing with conventional commit messages, pushing, and opening pull requests that auto-close the originating issue.

Prerequisites

Node.js

Node.js >= 20.12.0 is required.

AI provider (choose one)

OpenCode (default):

# Install OpenCode
curl -fsSL https://opencode.ai/install | bash
# or: npm install -g opencode-ai

# Configure an LLM provider (Anthropic, OpenAI, etc.)
opencode
# then run: /connect

GitHub Copilot:

# Requires an active GitHub Copilot subscription

# Install the Copilot CLI
npm install -g @github/copilot     # requires Node.js 22+
# or: brew install copilot-cli
# or: winget install GitHub.Copilot

# Authenticate
copilot
# then run: /login

For CI environments, set one of these environment variables instead of logging in interactively:

• COPILOT_GITHUB_TOKEN — GitHub PAT with Copilot Requests permission (highest priority)
• GH_TOKEN — standard GitHub CLI token
• GITHUB_TOKEN — commonly used in CI

Claude Code (--provider claude):

# Install Claude Code CLI
npm install -g @anthropic-ai/claude-code

# Authenticate
claude login
# or set ANTHROPIC_API_KEY in your environment

Default model: claude-sonnet-4. Available models: claude-sonnet-4, claude-sonnet-4-5, claude-opus-4-6, claude-haiku-3-5.

OpenAI Codex (--provider codex):

# Install the Codex CLI
npm install -g @openai/codex

# Authenticate via environment variable
export OPENAI_API_KEY=sk-...

Default model: o4-mini. Available models: o4-mini, o3-mini, codex-mini-latest.

Issue tracker (choose based on your repo)

GitHub (--source github):

# Install the GitHub CLI
# https://cli.github.com/

gh auth login

Azure DevOps (--source azdevops):

# Install the Azure CLI
# https://learn.microsoft.com/en-us/cli/azure/install-azure-cli

az login
az extension add --name azure-devops

Local markdown (--source md): No external tools or authentication required.

Windows users: See Windows prerequisites and setup for platform-specific installation commands, recommended configuration, and known limitations.

Installation

# Global install — adds `dispatch` to PATH
npm install -g @pruddiman/dispatch

# Run without installing
npx @pruddiman/dispatch

# Local project install
npm install --save-dev @pruddiman/dispatch
npx dispatch

Quick start

# Run interactive configuration wizard (first-time setup)
dispatch config

# Dispatch all open issues to AI agents
dispatch

# Dispatch specific issues
dispatch 42 43 44

# Dry run — list tasks without executing
dispatch --dry-run

# Use GitHub Copilot instead of OpenCode
dispatch --provider copilot

# Generate specs from issues (before dispatching)
dispatch --spec 42,43

Pipeline modes

| Mode | Flag | Description | |------|------|-------------| | Dispatch | (default) | Plan and execute tasks; manage full git lifecycle | | Spec generation | --spec | Convert issues into structured markdown spec files | | Fix tests | --fix-tests | Detect and auto-fix failing tests via AI |

Task files

Dispatch reads work items from markdown files with - [ ] ... checkbox syntax:

# My Feature

- [ ] (P) Add the login endpoint
- [ ] (P) Write unit tests for the login endpoint
- [ ] (S) Update the API documentation

Each unchecked item is dispatched to an AI agent. An optional mode prefix controls execution batching:

| Prefix | Mode | Behavior | |--------|------|----------| | (P) | Parallel | Tasks run concurrently (up to --concurrency) | | (S) | Serial | Tasks run one at a time | | (I) | Isolated | Each task runs in a dedicated worktree |

Tasks are marked [x] when complete. Rerunning dispatch skips already-completed tasks.

Configuration

Dispatch uses three-tier configuration: CLI flags override config file values, which override hardcoded defaults.

# Interactive wizard — guided setup for core AI settings (provider/model/source)
dispatch config

Config is stored at .dispatch/config.json (relative to the working directory where you run dispatch):

{
  "provider": "copilot",
  "model": "claude-sonnet-4-5",
  "source": "github",
  "testTimeout": 60
}

| Key | Description | |-----|-------------| | provider | AI backend: opencode (default), copilot, claude, or codex | | model | Model to use when spawning agents (provider-specific format) | | source | Issue tracker: github, azdevops, or md | | testTimeout | Test execution timeout in seconds (default: 60) |

Options reference

Dispatch mode

| Option | Default | Description | |--------|---------|-------------| | <issue-id...> | (all open) | Issue IDs to dispatch | | --provider <name> | opencode | AI backend (opencode, copilot, claude, codex) | | --source <name> | (auto-detected) | Datasource (github, azdevops, md) | | --dry-run | false | List tasks without executing | | --no-plan | false | Skip planner phase, execute directly | | --no-branch | false | Skip branch/push/PR lifecycle | | --concurrency <n> | (cpu/memory) | Max parallel dispatches | | --plan-timeout <min> | 10 | Planning timeout in minutes | | --plan-retries <n> | 1 | Retries after planning timeout | | --server-url <url> | (none) | Connect to a running provider server | | --cwd <dir> | process.cwd() | Working directory | | --verbose | false | Show detailed debug output |

Spec mode

| Option | Description | |--------|-------------| | --spec [values...] | Issue numbers, glob pattern, or description. Activates spec mode. Pass no args to regenerate all existing specs. | | --source <name> | Datasource override (auto-detected if omitted) | | --output-dir <dir> | Output directory for spec files (default: .dispatch/specs) | | --org <url> | Azure DevOps organization URL (required for azdevops) | | --project <name> | Azure DevOps project name (required for azdevops) |

Datasource auto-detection

When --source is not provided, Dispatch inspects the git origin remote URL:

| Remote URL contains | Detected source | |---------------------|----------------| | github.com | github | | dev.azure.com | azdevops | | visualstudio.com | azdevops |

For local-only workflows, pass --source md explicitly.

Exit codes

| Code | Meaning | |------|---------| | 0 | All tasks completed successfully | | 1 | One or more tasks failed, or a fatal error occurred | | 130 | SIGINT (Ctrl+C) | | 143 | SIGTERM |

Documentation

Full documentation is in the docs/ directory:

• Architecture Overview
• CLI & Orchestration
• Datasource System
• Provider System
• Task Parsing
• Planning & Dispatch
• Spec Generation
• Testing
• Windows

License

MIT