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.
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:
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 directory.
Code review — cross-agent validation
Have one agent write code or create a plan, then dispatch another to review:
# Codex has a native review command:
codex review --uncommitted # Review all local changes
codex exec review "Focus on error handling and edge cases"# Claude Code — pass the diff inline:
claude -p "Review the following diff for correctness, edge cases, and missed error handling:\n\n$(git diff)" \
--model opus --dangerously-skip-permissions
Get outside feedback on your work
Write your plan or analysis to a file, then ask a subagent to critique it:
cd /path/to/repo && claude -p "Read /tmp/my-plan.md and critique it. What am I missing? What could go wrong?" \
--model opus --dangerously-skip-permissions
Handling Failures
Timeout: If an agent times out (especially Claude Code on large repos), try: (1) a shorter, more focused prompt, (2) restricting tools with --allowedTools, (3) switching to Codex which handles large repos better
Garbage output: If results are incoherent, the prompt was probably too vague. Rewrite with more specific file paths and clearer instructions.
Session errors: Claude Code can hit "stale approval from interrupted session" — --dangerously-skip-permissions prevents this. If Codex errors, start a fresh exec session.
Compaction mid-task: If a Codex session runs long enough to compact, it may lose earlier context. Break long tasks into smaller sequential sessions.
CLI Reference
Claude Code
claude -p "YOUR PROMPT" --model MODEL --dangerously-skip-permissions
Flag
Purpose
-p / --print
Non-interactive mode, prints response and exits
--dangerously-skip-permissions
Skip approval prompts (prevents stale approval errors on timeout)
--model MODEL
Alias or model name accepted by the installed CLI; omit to use the configured default
--effort LEVEL
low, medium, high — controls reasoning depth
--append-system-prompt "..."
Inject additional system instructions
--allowedTools "Bash Edit Read"
Restrict available tools
--max-budget-usd N
Cap spend for the invocation
--add-dir DIR
Allow access to an additional directory; does not change the working directory
--output-format json
Structured output with session_id, cost_usd, duration_ms
Set Claude Code's working directory with cd /path/to/repo && claude ... in the Bash command, not with a Claude flag.
Codex
codex exec"YOUR PROMPT" --sandbox workspace-write
Flag
Purpose
exec
Non-interactive mode
-m MODEL
Model accepted by the installed CLI; omit to use the configured default
Both CLIs persist full session data (tool calls, reasoning, files read) to disk. The Bash output you see is just the final summary — the local session file is much richer.
Session storage paths
Claude Code:~/.claude/projects/<encoded-path>/<session-id>.jsonl
<encoded-path> = working directory with / replaced by - (e.g. /Users/foo/repos/bar becomes -Users-foo-repos-bar)
Use --output-format json to get the session_id in the response
Use session resumption to continue a line of investigation without re-providing all context:
Claude Code:
claude -r SESSION_ID -p "Follow up: now check if..."# Resume by ID
claude -c -p "Also check..."# Continue most recent
claude -r SESSION_ID --fork-session -p "Try differently"# Fork (new ID, keeps history)
Codex:
codex exec resume SESSION_ID "Follow up prompt"# Resume by ID (non-interactive)
codex exec resume --last "Follow up prompt"# Resume most recent (non-interactive)
codex resume SESSION_ID "Follow up prompt"# Resume by ID (interactive)
codex resume --last "Follow up prompt"# Resume most recent (interactive)
codex fork SESSION_ID "Try a different approach"# Fork session (interactive)
Note: codex exec resume works non-interactively. codex resume and codex fork are interactive only.
When to analyze past sessions
Don't run history-analyzer after every dispatch — your reflection agent already captures insights naturally, and single-session analysis produces overly detailed notes.
Do use history-analyzer for bulk migration when bootstrapping memory from months of accumulated history (e.g. during /init). See the initializing-memory skill's historical session analysis reference.
Direct uses for session files:
Resume an investigation (see above)
Review what an agent actually did (read the JSONL file directly)
