/dispatching-coding-agents

name: dispatching-coding-agents
description: Dispatch stateless coding agents (Claude Code or Codex) via Bash. Use when you're stuck, need a second opinion, or need parallel research on a hard problem. They have no memory — you must provide all context.

Dispatching Coding Agents

You can shell out to **Claude Code** (`claude`) and **Codex** (`codex`) as stateless sub-agents via Bash. They have filesystem and tool access (scope depends on sandbox/approval settings) but **zero memory** — every session starts from scratch.

**Default to `run_in_background: true`** on the Bash call so you can keep working while they run. Check results later with `TaskOutput`. Don't sit idle waiting for a subagent.

The Core Mental Model

Claude Code and Codex are highly optimized coding agents, but are re-born with each new session. Think of them like a brilliant intern that showed up today. Provide them with the right instructions and context to help them succeed and avoid having to re-learn things that you've learned.

You are the experienced manager with persistent memory of the user's preferences, the codebase, past decisions, and hard-won lessons. **Give them context, not a plan.** They won't know anything you don't tell them:

• **Specific task**: Be precise about what you need — not "look into the auth system" but "trace the request flow from the messages endpoint through to the LLM call, cite files and line numbers."
• **File paths and architecture**: Tell them exactly where to look and how pieces connect. They will wander aimlessly without this.
• **Preferences and constraints**: Code style, error handling patterns, things the user has corrected you on. Save them from making mistakes you already learned from.
• **What you've already tried**: If you're dispatching because you're stuck, this prevents them from rediscovering your dead ends.

If a subagent needs clarification or asks a question, respond in the same session (see Session Resumption below) — don't start a new session or you'll lose the conversation context.

When to Dispatch (and When Not To)

Dispatch for:

• **Hard debugging** — you've been looping on a problem and need fresh eyes
• **Second opinions** — you want validation before a risky change
• **Parallel research** — investigate multiple hypotheses simultaneously
• **Large-scope investigation** — tracing a flow across many files in an unfamiliar area
• **Code review** — have another agent review your diff or plan

Don't dispatch for:

• Simple file reads, greps, or small edits — faster to do yourself
• Anything that takes less than ~3 minutes of direct work
• Tasks where you already know exactly what to do
• When context transfer would take longer than just doing the task

Choosing an Agent and Model

Different agents have different strengths. Track what works in your memory over time — your own observations are more valuable than these defaults.

Categories

**Codex:**

• Use the configured default model. Model catalogs and account access change frequently, so only pass `--model` when the user explicitly requests one.
• If a requested model is rejected, inspect the installed CLI and account configuration rather than guessing another model name.

**Claude Code:**

• `opus` — Excellent writer. Best for docs, refactors, open-ended tasks, and vague instructions.
• Strengths: Excellent writer, understands vague instructions, excellent for coding but also general-purpose
• Weaknesses: Tends to generate "slop", writing excessive quantities of code unnecessarily. Can hang on large repos.

Cost and speed tradeoffs

• Use each CLI's configured default model unless the task requires a model the user explicitly requested
• Use `--max-budget-usd N` (Claude Code) to cap spend on exploratory tasks

Known quirks

• **Claude Code can hang on large repos** with unrestricted tools — consider `--allowedTools "Read Grep Glob"` (no Bash) and shorter timeouts for research tasks
• **Codex compactions can destroy long trajectories** — for very long tasks, prefer multiple shorter sessions over one marathon
• **Opus tends to over-generate** — produces more code than necessary. Good for exploration, verify before applying.

Prompting Subagents

Prompt template

TASK: [one-sentence summary]

CONTEXT:
- Repo: [path]
- Key files: [list specific files and what they contain]
- Architecture: [brief relevant context]

WHAT TO DO:
[what you need done — be precise, but let them figure out the approach]

CONSTRAINTS:
- [any preferences, patterns to follow, things to avoid]
- [what you've already tried, if dispatching because stuck]

OUTPUT:
[what you want back — a diff, a list of files, a root cause analysis, etc.]

What makes a good prompt

• **Be specific about files** — "look at `src/agent/message.ts` lines 40-80" not "look at the message handling code"
• **State the output format** — "return a bullet list of findings" vs. leaving it open-ended
• **Include constraints** — if the user prefers certain patterns, say so explicitly
• **Provide what you've tried** — when dispatching because you're stuck, this prevents them from repeating your dead ends

Dispatch Patterns

Parallel research — multiple perspectives

Run Claude Code and Codex simultaneously on the same question via separate Bash calls in a single message (use `run_in_background: true`). Compare results for higher confidence.

Background dispatch — keep working while they run

Use `run_in_background: true` on the Bash call to dispatch async. Continue your own work, then check results with `TaskOutput` when ready.

Deep investigation

For hard problems, use the configured model in a writable sandbox:

codex exec "YOUR PROMPT" --sandbox workspace-write -C /path/to/repo

Claude Code does not support a `-C` working-directory flag. Use `cd /path/to/repo && claude ...` inside the Bash command. Use `--add-dir` only to grant access to additional directories outside the current working direct