---
name: ai-cli-dispatch
description: Dispatch AI CLI coding tasks to available clients (Codex, Claude Code, OpenCode) with automatic discovery, version checking, and execution.
metadata: {"clawdbot":{"emoji":"robot","requires":{"bins":["node"]}}}
---

# AI CLI Dispatch

Use this skill when the user wants to run a coding task through an AI CLI client such as Codex, Claude Code, or OpenCode.

The skill discovers installed clients, resolves versions, selects the best available tool, and forwards the task with arguments intact.

Use the local helper from the installed skill directory:

```bash
cd ~/.openclaw/workspace/skills/ai-cli-dispatch
scripts/ai-cli-dispatch --help
```

## Setup

```bash
cd ~/.openclaw/workspace/skills/ai-cli-dispatch
npm install
```

## Commands

```bash
scripts/ai-cli-dispatch list --json
scripts/ai-cli-dispatch run --client codex --prompt "refactor this function"
scripts/ai-cli-dispatch run --client claude --prompt "add tests for auth middleware"
scripts/ai-cli-dispatch run --client opencode --prompt "migrate to ESM"
scripts/ai-cli-dispatch dispatch "use codex to write tests"
```

Use `--json` for machine-readable command output. Use `--sync` with `run` or `dispatch` to block until the client returns; the default is async (starts a background job and returns the job ID immediately).

## Client Discovery

The skill searches for the following clients in order:

- `codex` — OpenAI Codex CLI
- `claude` — Anthropic Claude Code
- `opencode` — OpenCode CLI

Run `list` to see which clients are installed and their resolved versions.

## Background Jobs

For long-running or fire-and-forget tasks, use the programmatic job API or invoke `run` / `dispatch` without `--sync`:

```typescript
import { startJob, getJob, cancelJob, listJobs, cleanupJobs } from "./src/jobs.js";

// Start a detached job
const job = await startJob("codex", "refactor auth module", { timeoutMs: 300_000 });
console.log(job.id); // e.g. "a1b2c3d4..."
console.log(job.status); // "running"

// Poll for completion
const latest = getJob(job.id);
console.log(latest.status); // "running" | "completed" | "failed" | "timed_out" | "cancelled"

// Cancel a running job
cancelJob(job.id);

// List all jobs (newest first)
const jobs = listJobs(); // Job[]
const running = listJobs({ filter: "running" });

// Clean up job files older than 24 hours (default)
cleanupJobs({ maxAgeMs: 24 * 60 * 60 * 1000 });
```

Job files are stored under `~/.openclaw/ai-cli-dispatch/jobs/<jobId>.json` and include stdout, stderr, exit code, and timing.

## Output Rules

- Normal JSON output redacts local file paths and credential metadata.
- Use `--debug` only when deeper troubleshooting requires internal paths and resolved config metadata.