dispatch-cli-agent

Dispatch prompts to external CLI agents and collect results.

Supported CLIs

CLI	Command	Output	Reference
Claude Code	claude -p "prompt" --output-format json	JSON (result, session_id, usage)	claude-code.md
Codex CLI	codex exec "prompt" --json	JSONL events	codex-cli.md
Gemini CLI	gemini -p "prompt"	Plain text (recommended; --output-format json may not print to stdout)	gemini-cli.md
Copilot CLI	copilot -p "prompt" -s	Plain text (silent mode)	copilot-cli.md

Dispatch Workflow

1. Write the prompt file

Write the prompt to .dispatch/<cli>-<timestamp>.md so it's inspectable and replayable.

mkdir -p .dispatch
# Write prompt file using the Write tool
# Path: .dispatch/claude-code-2024-03-04T12-00-00.md

2. Read the CLI reference

Read references/<cli>.md for the target CLI to get exact flags. Each reference includes pipe patterns, permission flags, and output parsing.

3. Launch via background Bash tasks

IMPORTANT: Do NOT use Agent sub-agents — they cannot get Bash permissions to run external CLIs. Instead, run CLI commands directly as background Bash tasks (run_in_background: true). This still parallelizes the work while keeping output in files rather than the context window.

For single dispatch:

# Bash tool with run_in_background: true
cat .dispatch/<file>.md | claude -p - \
  --output-format json \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 5 \
  --no-session-persistence 2>/dev/null \
  | jq -r '.result' > .dispatch/output-claude.md

For parallel fan-out, launch multiple Bash calls in a single message (all with run_in_background: true):

# Bash 1 — Claude Code
cat .dispatch/prompt.md | claude -p - --output-format json \
  --allowedTools "Read,Glob,Grep" --no-session-persistence 2>/dev/null \
  | jq -r '.result' > .dispatch/output-claude.md

# Bash 2 — Codex CLI
cat .dispatch/prompt.md | codex exec - --json --ephemeral 2>/dev/null \
  | grep '"type":"item.completed"' \
  | jq -rs '[.[].item.text] | join("\n")' > .dispatch/output-codex.md

# Bash 3 — Gemini CLI (use plain text, --output-format json may not produce stdout)
cat .dispatch/prompt.md | gemini -p - 2>/dev/null \
  > .dispatch/output-gemini.md

# Bash 4 — Copilot CLI
cat .dispatch/prompt.md | copilot -p - -s --no-ask-user --no-custom-instructions 2>/dev/null \
  > .dispatch/output-copilot.md

4. Collect results

Read the output files after all background tasks complete:

1. Read .dispatch/output-<cli>.md for each CLI
2. Aggregate feedback
3. Synthesize a unified response

Safe Defaults

Always use read-only/minimal permissions unless the caller explicitly needs more:

CLI	Safe flags
Claude Code	--allowedTools "Read,Glob,Grep" --no-session-persistence
Codex CLI	--ephemeral (default sandbox is read-only)
Gemini CLI	(default prompts for approval)
Copilot CLI	--no-ask-user --no-custom-instructions

File-Based Output (alternative)

When JSON stdout is insufficient or output is very large:

# Claude Code: capture to file, parse later
claude -p "prompt" --output-format json > .dispatch/output-claude.json

# Codex CLI: use -o flag
codex exec "prompt" -o .dispatch/output-codex.md --ephemeral

# Copilot CLI: use --share flag
copilot -p "prompt" -s --share .dispatch/output-copilot.md

Tips

• Set --max-turns / --max-autopilot-continues to prevent runaway agents
• Set --max-budget-usd (Claude Code) for cost control
• Use --model to select cheaper models for review tasks
• Prompt files in .dispatch/ can be reused — pipe the same file to multiple CLIs
• Ensure .dispatch/ is ignored (e.g., add it to a .gitignore file or .git/info/exclude)