cli-dispatch: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

cli-dispatch is a Claude Code plugin (not an npm package — there is no package.json, no build step, no bundler; the demo video source under assets/demo-src/ is gitignored, local only). It ships slash commands, a SessionStart hook, a skill, and standalone CLI scripts that let Claude Code delegate work to six external "worker" backends — DeepSeek (via claude pointed at DeepSeek's API), Antigravity/Gemini (agy), OpenAI Codex (codex), OpenCode (opencode, via OpenRouter), GitHub Copilot (copilot), and Ollama (ol: the same claude pointed at a local Ollama, selected by CLAUDE_DS_BACKEND=ollama inside the DeepSeek pipeline; ol-agent is a shim over ds-agent) — since Claude Code's built-in subagent tool only supports Anthropic models. It ships one thin subagent, agents/runner.md (cli-dispatch:runner, haiku, Bash-only — a forwarder, see "The deterministic runner + escalation path" below); the five agents/*-runner.md LLM babysitters were deleted in 4.0.0.

Everything the plugin installs lives under plugins/cli-dispatch/:

• commands/*.md — slash commands (/cli-dispatch:*). Each is markdown with a fenced bash (and sometimes PowerShell) block that Claude Code executes directly — there is no compiled command layer. Read-only commands should instead pre-execute an extracted script via a leading !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/<name>.sh"` line: embedded shell is paid twice (once as the markdown's input tokens, again as output when the model re-emits it verbatim as a Bash tool call), while a ! line runs before the model sees anything and injects only the output. doctor, sessions and help are converted; balance was too until 6.1.5 and now runs its script from one fenced call (see "Non-obvious constraints"); clean is a thin call to the installed cli-dispatch-clean binary (not pre-executed — it mutates); the rest are not yet. Two traps: ${CLAUDE_PLUGIN_ROOT} is interpolated into the ! command string but not exported into the subprocess, so a script that needs it must take it as an argument (this silently killed doctor's staleness check in 4.9.0); and a mutating command must never pre-execute its mutation — clean --schedule must not pre-execute install/uninstall either; those stay a deliberate call.
• scripts/ — the actual installed CLIs. Per-backend: ds-agent, ag-agent, cx-agent, oc-agent, cp-agent + their *-stream siblings and *-worktree-run.sh runners. Backend-agnostic: cli-dispatch-run (the deterministic runner — the delegation path), cli-dispatch-wait, cli-dispatch-clean, cli-dispatch-gain, cli-dispatch-run-summary.sh (the compact verdict summary shared by /cli-dispatch:run and a detached run's summary.txt; unlike the pre-execution scripts below, install.sh DOES copy it — to ~/.local/share/cli-dispatch/, not PATH — because the installed runner needs it), and cli-dispatch-statusline.sh (the [CD] statusline fragment — bash-only by design, glob-loaded from the plugin cache rather than installed to ~/.local/bin). The pre-execution scripts (cli-dispatch-doctor.sh, cli-dispatch-sessions.sh, cli-dispatch-balance.sh, cli-dispatch-help.sh, cli-dispatch-clean-schedule.sh + its .ps1 twin; cli-dispatch-status.ps1 stays only as doctor's native-Windows fallback) likewise run from the plugin cache and are not installed, so they can never go stale relative to the plugin — do not add them to install.sh. setup-form.mjs (the one-shot browser form for keys and model names) follows the same rule — install.sh/install.ps1/setup.md run it from the plugin dir — and being node it has no .ps1 twin; cli-dispatch-pane-read.mjs (the /cli-dispatch-runs pane's byte-range file reader, run by the mod) follows it too. Bash/PowerShell wrappers around Node engines (*-stream-parse.mjs parsers, verdict-writer.mjs, gain-report.mjs, drift-report.mjs, cli-dispatch-clean.mjs). install.sh/install.ps1 copy these into ~/.local/bin (wrappers) and ~/.local/share/cli-dispatch/ (engines + shared libs).
• hooks/hooks.json — the SessionStart hook registration. Wires scripts/policy-inject.mjs to all five matchers (startup/resume/clear/compact/fork); compact and fork matter because compaction drops the injected policy from a long session's context (#118).
• hooks/cli-dispatch-mod.tsx — the plugin's mod (Claude Code 2.1.287+), named under modules in the same hooks.json: a band above the prompt with this session's workers; a tool.call guard that refuses Edit/Write into a repo while a worktree run for it is live (the leak check would blame the worker); and the mcp__cli-dispatch__dispatch tool (6.3.0), which runs cli-dispatch-run --detach + cli-dispatch-wait --run itself in one tool call — the runner agent's job with no LLM turns. It is not registered inside a worker (CLI_DISPATCH_WORKER=1). Its state contract is types/index.d.ts (named as types in plugin.json); its tests are tests/mod.test.ts. /cli-dispatch-runs is its run monitor pane (this session's runs, one chronological Flow built from transcript.jsonl in its own frame, which the pane's ui.scroll hook scrolls, masked); the band's liveness test is isRunAlive. It reads session dirs with the same root resolution and 90 s liveness window as cli-dispatch-statusline.sh.
• skills/ds-delegate/SKILL.md — the ds-delegate skill.