title: Fan-Out Fan-In slug: fan-out-fan-in category: workflow-pattern status: proven difficulty: intermediate tags: [parallelism, sub-agents, orchestration, throughput] prerequisites: [basic-cli-usage, git-worktrees] estimated_time: 15min to learn, varies per task cost_per_use: "$0.50-$3.00 depending on sub-task count"

Fan-Out Fan-In

Problem

You have a large task that decomposes into independent pieces — migrating 12 API endpoints, reviewing 8 modules, or generating tests for 15 files. Running them sequentially wastes time and money because the agent idles between context switches. You need a way to dispatch parallel work and merge the results.

Solution

1. Decompose the task into independent units (files, modules, endpoints).
2. Dispatch a separate agent (or sub-process) for each unit.
3. Collect results into a shared location (branch, directory, or summary file).
4. Merge and review the combined output.

Step-by-Step

1. Identify the list of independent work items.
2. Write a dispatch script or use shell parallelism (xargs -P, parallel, or background jobs).
3. Each sub-agent works in its own worktree or output file.
4. After all complete, review diffs and consolidate.

When to Use

• Migrating or refactoring many similar files
• Generating tests across multiple modules
• Reviewing a large PR split by directory
• Bulk documentation generation
• Any task where sub-items share no dependencies

When NOT to Use

• Tasks with sequential dependencies (step 2 needs step 1's output)
• When shared state or files would cause merge conflicts
• Small tasks where orchestration overhead exceeds the work itself
• When you need tight consistency across all outputs (use a single agent instead)

Example: Claude Code

# Define the files to process
FILES=(
  src/api/users.ts
  src/api/orders.ts
  src/api/products.ts
  src/api/payments.ts
)

# Fan-out: launch a sub-agent per file in the background
for file in "${FILES[@]}"; do
  claude -p "Write unit tests for $file. Output tests to tests/$(basename $file .ts).test.ts. \
    Follow existing test patterns in the repo. Do not modify the source file." \
    --allowedTools Edit,Read,Bash,Glob,Grep &
done

# Fan-in: wait for all sub-agents to finish
wait
echo "All sub-agents complete."

# Review combined results
git diff --stat
claude -p "Review all new test files in tests/. Check for consistency, \
  missing edge cases, and correct imports. Summarize findings."

Example: Codex CLI

# Fan-out with codex using xargs for parallelism
echo "src/api/users.ts
src/api/orders.ts
src/api/products.ts
src/api/payments.ts" | xargs -P 4 -I {} codex -q \
  "Write unit tests for {}. Save to tests/$(basename {} .ts).test.ts."

# Fan-in: review results
codex -q "Review all files in tests/ for consistency and correctness."

Cost Estimate

Orchestration overhead (dispatch + review pass) adds ~$0.20-$0.40.

Maturity Notes

Status: Proven. This pattern works well for homogeneous tasks (same operation, different targets). Results vary when sub-tasks are heterogeneous or when outputs must be tightly coordinated. Always include a final review/merge pass — sub-agents may produce inconsistent styles or duplicate helper functions.

Related

• Pattern: Parallel Worktree
• Module: Agent Teams
• Module: Headless & CI/CD