Dispatch to Claude Code

Dispatch sends an implementation plan to Claude Code (or Codex) for automated execution. The CLI adapter creates a branch, implements the plan, and opens a PR with a self-review — all tracked as a background task in Supabase.

How It Works

The dispatch flow chains plan generation with automated execution:

A plan is generated (see Implementation Plans) or provided directly
The plan Markdown and a target branch name are sent to the dispatch endpoint
A dispatch-cc task is created in Supabase and picked up by the local runner
The runner spawns the configured CLI adapter (Claude or Codex) with the plan as the prompt
The CLI works in the repository, creating commits on the specified branch
When done, the CLI creates a PR and runs a self-review
The task completes with the PR URL stored in the result

CLI Adapter System

Oversight uses a pluggable adapter pattern to support multiple AI CLI tools. Each adapter implements a common CLIAdapter interface:

CLIAdapter interface ts

interface CLIAdapter {
  name: string;
  isAvailable(): boolean;
  buildArgs(prompt: string, opts?: { model?: string; cwd?: string }): string[];
  buildEnv(): Record<string, string | undefined>;
  parseOutputLine(line: string): string | null;
  isRetryableError(errorMsg: string, recentOutput: string[]): boolean;
  spawn(prompt: string, cwd: string): ChildProcess;
}

Supported Adapters

Adapter	CLI Binary	Output Format	Notes
`ClaudeAdapter`	`claude`	stream-json	Default adapter. Uses `--print --verbose --output-format stream-json`
`CodexAdapter`	`codex`	JSON events	Uses `exec --json --full-auto`

Task Tracking

Dispatch tasks are tracked in the Supabase tasks table with task type dispatch-cc. The runner streams progress updates in real time:

Step	Description
`dispatching`	Setting up the CLI process and branch
`running`	Claude Code is implementing the plan (streams output lines)
`complete`	Done; result contains the PR URL if one was created

The output_log field stores a timestamped array of every output line, enabling post-hoc debugging:

OutputLogEntry ts

interface OutputLogEntry {
  ts: string;   // ISO timestamp
  line: string;
}

Monitoring Dispatch Progress

Progress is pushed via Supabase Realtime. The web UI subscribes to task updates and renders a live output log with the last 50 lines of CLI output. The runner also detects PR URLs in the output stream and stores them in the task result.

PR Detection: The runner scans each output line for URLs matching https://github.com/*/pull/* and captures the first match as the PR URL.

Timeouts and Retries

Dispatch tasks have a 30-minute hard timeout. The runner also implements transient error detection with automatic retries for common failures:

HTTP 429/502/503/529 responses (rate limits, overloaded)
Network errors: ETIMEDOUT, ECONNRESET, ECONNREFUSED
Explicit rate limit messages in the output stream

API Endpoint

Method	Path	Description
POST	`/api/copilot/dispatch`	Dispatch a plan to Claude Code

Request Body

DispatchToClaudeCodeRequest ts

interface DispatchToClaudeCodeRequest {
  repoId: number;
  planMarkdown: string;
  branchName?: string;  // defaults to oversight/plan-{timestamp}
}

Response

DispatchToClaudeCodeResponse ts

interface DispatchToClaudeCodeResponse {
  taskId: string;
}

Configuration

Environment Variable	Default	Description
`OVERSIGHT_CLI`	Auto-detect	Force a specific adapter: `claude` or `codex`

When OVERSIGHT_CLI is not set, the runner auto-detects: it checks for claude first, then falls back to codex. If neither is found, dispatch tasks will fail with a clear error message.

Rollback on Failure

If the dispatch task fails (CLI crash, timeout, or non-retryable error), the task status is set to error with the failure message and full output log preserved. Since all work happens on a dedicated branch, the main branch is never affected — you can inspect the partial work on the branch or simply delete it.