dispatching-parallel-agents-codex

Dispatching Parallel Agents

Overview

When you have multiple unrelated tasks (different subsystems, different bugs), working them sequentially wastes time. Each thread is independent and can happen in parallel.

Core principle: Dispatch one codex_implement per independent problem domain. Let them work concurrently.

Parallel execution MUST use codex_implement calls. You cannot implement tasks yourself. This skill dispatches Codex workers — Claude orchestrates, Codex executes.

When to Use

digraph when_to_use {
    "Multiple independent tasks?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single codex_implement handles all" [shape=box];
    "One codex_implement per domain" [shape=box];
    "Can they run without shared state?" [shape=diamond];
    "Sequential codex_implement" [shape=box];
    "Parallel dispatch" [shape=box];

    "Multiple independent tasks?" -> "Are they independent?" [label="yes"];
    "Are they independent?" -> "Single codex_implement handles all" [label="no - related"];
    "Are they independent?" -> "Can they run without shared state?" [label="yes"];
    "Can they run without shared state?" -> "Parallel dispatch" [label="yes"];
    "Can they run without shared state?" -> "Sequential codex_implement" [label="no - shared state"];
}

Use when:

• 3+ failing test files with different root causes
• Multiple subsystems broken independently
• Each problem can be understood without context from others
• No shared state between threads (no same-file edits)

Don't use when:

• Failures are related (fix one might fix others)
• Need to understand full system state first
• Threads would edit the same files

The Pattern

1. Identify Independent Domains

Group tasks by what's being changed:

• Thread A: Agent forwarding contract in scripts/
• Thread B: Test fixture updates in tests/fixtures/
• Thread C: Schema validation in schemas/

Each domain is independent — Thread A doesn't touch Thread B's files.

2. Create Focused Task Prompts

Each codex_implement call gets:

• Specific scope: One file or subsystem
• Clear goal: What done looks like
• Constraints: Don't change other code
• Expected output: Summary of what was found and fixed

3. Dispatch in Parallel

Call multiple codex_implement tools in a single message so they run concurrently:

{
  "tool": "codex_implement",
  "arguments": {
    "taskId": "parallel-A",
    "prompt": "Fix the 3 failing tests in tests/adapter/codex-run.test.mjs. These are timeout-related. Root cause and fix only — do not touch other test files.",
    "workspaceRoot": "/absolute/path/to/your/repo"
  }
}

{
  "tool": "codex_implement",
  "arguments": {
    "taskId": "parallel-B",
    "prompt": "Fix the schema mismatch in schemas/implementer-result.schema.json. The 'tests' field is missing from the required array. Do not touch other schemas.",
    "workspaceRoot": "/absolute/path/to/your/repo"
  }
}

{
  "tool": "codex_implement",
  "arguments": {
    "taskId": "parallel-C",
    "prompt": "Update the fixture in tests/fixtures/sample-result.jsonl to match the new implementer-result schema. Only touch that fixture file.",
    "workspaceRoot": "/absolute/path/to/your/repo"
  }
}

4. Review and Integrate

When all threads return, each response includes a sessionId — capture it for follow-up:

• Read each summary
• Verify fixes don't conflict (check for same-file edits)
• Run full test suite
• Use codex_resume with the returned taskId and sessionId if any thread needs follow-up

Writing Good Prompts

Good prompts are:

1. Focused - One clear problem domain
2. Self-contained - All context needed to understand the problem
3. Specific about constraints - Name files they must NOT touch
4. Clear about output - Summary of root cause and changes made

Bad:

"Fix all the tests"  ← agent gets lost
"Fix the race condition"  ← agent doesn't know where

Good:

"Fix the 3 failing tests in tests/adapter/codex-run.test.mjs.
Tests: [list test names + error messages].
Root cause is likely X. Fix by Y.
Do NOT change production code.
Return: root cause found and what you changed."

Common Mistakes

Too broad: Agent gets lost in unrelated code. No constraints: Agent refactors everything. Vague output: You don't know what changed. Overlapping scope: Threads edit same files, creating conflicts.

When NOT to Use

Related failures: Investigate together, fixing one might fix others. Need full context: Understanding requires seeing the whole system. Exploratory debugging: You don't know what's broken yet — use codex_debug first. Shared state: Threads would interfere (editing same files).

After All Threads Return

1. Review each summary — understand what changed
2. Check for conflicts — did any threads edit the same file?
3. Run full suite — npm test
4. Resume if needed — use codex_resume with the appropriate taskId and sessionId
5. Spot check — Codex can make systematic errors; read the diff

Key Benefits

1. Parallelization — multiple threads work simultaneously
2. Focus — each thread has narrow scope
3. Independence — threads don't interfere
4. Speed — N problems solved in time of 1