| name | batching-patterns |
| description | Batches related operations into single messages for maximum parallelism. Use when launching multiple agents, reading many files, or removing sequential execution bottlenecks. |
| user-invocable | false |
Batching Patterns
Version: 1.0.0
Purpose: The Golden Rule of Claude Code execution -- batch operations for maximum parallelism
Status: Production Ready
Overview
The Golden Rule of Claude Code performance:
"1 MESSAGE = ALL RELATED OPERATIONS"
Every tool call within a single message executes in parallel (when no dependencies exist). Every separate message introduces a sequential round-trip. This distinction is the difference between a 2-minute workflow and a 10-minute one.
Sequential (5 separate messages):
Message 1: Task(agent-1) → 2 min
Message 2: Task(agent-2) → 2 min (waits for agent-1!)
Message 3-5: ... → 2 min each
Total: ~10 minutes (serial)
Batched (1 message):
Message 1: Task(agent-1) + Task(agent-2) + ... + Task(agent-5)
Total: ~2 minutes (parallel, limited by slowest agent)
Speedup: 5x
Each message carries API round-trip overhead. Batching eliminates N-1 round-trips.
The Batching Principle
Claude Code has a simple execution model:
- Within ONE message: Same tool type calls execute in parallel (no data dependencies)
- Across SEPARATE messages: Tool calls execute sequentially
- Mixed tool types in ONE message: May force sequential execution
Same tool type in one message = PARALLEL
Task(A) + Task(B) + Task(C) → All run simultaneously
Different tool types in one message = SEQUENTIAL (often)
TaskCreate(...) + Task(A) + Bash(...) → May run one at a time
Separate messages = ALWAYS SEQUENTIAL
Message 1: Task(A) → completes first
Message 2: Task(B) → starts only after A finishes
Why Same Tool Type Signals Independence:
Multiple calls of the same tool type (all Task, all Read, all Grep) signal independent operations that can run concurrently. Mixing tool types breaks this signal because different types often have implicit ordering requirements.
Batching Patterns by Tool Type
Task Tool Batching
The most impactful tool to batch -- each agent runs for minutes.
❌ Sequential (3 separate messages):
Message 1: Task(security-reviewer) → 3 min
Message 2: Task(perf-reviewer) → 2 min (waits!)
Message 3: Task(a11y-reviewer) → 2 min (waits!)
Total: ~7 minutes
✅ Batched (1 message):
Task(security-reviewer) + Task(perf-reviewer) + Task(a11y-reviewer)
Total: ~3 minutes (3 agents parallel)
Speedup: 2.3x
Agents are independent when they: read same input but don't modify it, write to different output files, perform different analysis, don't need each other's results.
File Operations Batching
❌ Sequential Reads:
Message 1: Read("src/auth.ts") → round-trip
Message 2: Read("src/middleware.ts") → round-trip
Message 3: Read("src/routes.ts") → round-trip
Total: 3 round-trips
✅ Batched Reads:
Read("src/auth.ts") + Read("src/middleware.ts") + Read("src/routes.ts")
Total: 1 round-trip (3x faster)
❌ Sequential Searches:
Message 1: Grep("TODO", path="src/")
Message 2: Grep("FIXME", path="src/")
Message 3: Glob("**/*.test.ts")
✅ Batched Searches:
Grep("TODO") + Grep("FIXME") + Glob("**/*.test.ts")
All parallel in 1 round-trip
⚠️ Write/Edit Caution:
❌ Edit("src/auth.ts", change_1) + Edit("src/auth.ts", change_2) ← Conflict!
✅ Edit("src/auth.ts", change_1) + Edit("src/routes.ts", change_2) ← Safe
Rule: Different files = safe to batch. Same file = must be sequential.
Tasks Batching
❌ Individual Calls (5 round-trips):
TaskCreate({ id: "1", title: "Step 1", status: "pending" })
TaskCreate({ id: "2", title: "Step 2", status: "pending" })
...
✅ Single Call (1 round-trip):
TaskCreate({ id: "1", title: "Step 1", status: "pending" })
TaskCreate({ id: "2", title: "Step 2", status: "pending" })
TaskCreate({ id: "3", title: "Step 3", status: "pending" })
# All in same message = parallel execution
Bash Batching
❌ Sequential Independent Commands:
Message 1: Bash("npm run lint")
Message 2: Bash("npm run typecheck")
Message 3: Bash("npm run test")
✅ Parallel Independent Commands (1 message):
Bash("npm run lint") + Bash("npm run typecheck") + Bash("npm run test")
✅ Dependent Commands Chained (1 Bash call):
Bash("mkdir -p ai-docs && cp template.md ai-docs/plan.md")
The 4-Message Pattern (Reference)
The canonical batching template from multi-agent-coordination:
Message 1: Preparation (Bash/Write only)
- Create directories, write context files, validate inputs
- NO Task calls, NO Tasks
Message 2: Parallel Execution (Task only)
- ALL agents in SINGLE message, ONLY Task calls
- Same tool type = true parallel execution
Message 3: Consolidation (Task only)
- Consolidation agent reads all output files
Message 4: Present Results
- Show user final consolidated results
Why 4 messages: Each depends on the previous (agents need context, consolidation needs agent outputs, presentation needs consolidated result). This is the minimum sequential steps.
Anti-Patterns (Critical)
Anti-Pattern 1: Sequential Task Launches
❌ Message 1: Task(agent-1) // 2 min
❌ Message 2: Task(agent-2) // 2 min (waits for agent-1!)
❌ Message 3: Task(agent-3) // 2 min (waits for agent-2!)
Total: 6 minutes
✅ Message 1: Task(agent-1) + Task(agent-2) + Task(agent-3) // All parallel!
Total: 2 minutes (3x speedup)
Anti-Pattern 2: Mixing Tool Types in Execution Message
❌ Mixed Tools (sequential):
TaskCreate({...}) // Tool type A
Task(security-reviewer) // Tool type B
Bash("echo 'starting'") // Tool type C
Task(perf-reviewer) // Tool type B
✅ Separated (parallel execution):
Message 1: TaskCreate({...}) + Bash("echo 'starting'") // Preparation
Message 2: Task(security-reviewer) + Task(perf-reviewer) // Execution (parallel)
Anti-Pattern 3: Individual Tasks Calls
❌ 5 separate TaskCreate calls across messages = 5 round-trips
✅ 5 TaskCreate calls in 1 message = 1 round-trip (parallel)
Anti-Pattern 4: Sequential File Reads
❌ 5 separate Read messages = 5 round-trips
✅ 5 Read calls in 1 message = 1 round-trip (5x faster)
Anti-Pattern 5: Unnecessary Dependencies
❌ False Dependencies:
Message 1: Grep("authentication") // Wait...
Message 2: Grep("authorization") // Wait...
Message 3: Glob("**/*.middleware.ts") // Wait...
✅ Recognize Independence:
Message 1: Grep("authentication") + Grep("authorization") + Glob("**/*.middleware.ts")
Dependency Detection Checklist:
Before splitting across messages, ask:
- Does B need the OUTPUT of A? If no, batch.
- Do both write to the SAME file? If no, batch.
- Does the ORDER matter? If no, batch.
- Is B CONDITIONAL on A's result? If no, batch.
If all four are "no," operations are independent -- batch them.
When NOT to Batch
- Data dependencies: Developer needs architect's plan before implementing
- Same-file modifications: Two edits to the same file must be sequential
- Sequential phases: Plan -> Implement -> Test -> Review (each depends on previous)
- Order-dependent operations:
npm install && npm build && npm test
- Conditional execution: Next action depends on previous result (test pass/fail)
CORRECT - Sequential:
Message 1: Task(architect) → writes plan.md
Message 2: Task(developer) → reads plan.md (depends on Message 1)
CORRECT - Chained:
Bash("npm install && npm run build && npm run test")
Performance Impact
Scenario: 5-Agent Code Review
Sequential: 10 min + 5 round-trips | Batched: 3 min + 1 round-trip | 3.3x
Scenario: 7 Codebase Searches
Sequential: ~21 seconds | Batched: ~3 seconds | 7x
Scenario: 10 File Reads
Sequential: ~20 seconds | Batched: ~2 seconds | 10x
Speedup Formula:
Sequential = N * (execution + round_trip)
Batched = max(executions) + round_trip
Speedup = approximately N (for identical operations)
Context Benefits: Fewer messages = less context consumed = more room for useful work.
Best Practices
Do:
- ✅ Launch ALL independent agents in a single message (biggest speedup)
- ✅ Read all needed files in one message before processing
- ✅ Run all independent searches (Grep + Glob) in parallel
- ✅ Create all task items in a single message
- ✅ Use the same tool type for parallel operations
- ✅ Check the dependency checklist before splitting across messages
- ✅ Follow the 4-Message Pattern for multi-agent workflows
- ✅ Chain dependent Bash commands with && in a single call
Don't:
- ❌ Launch agents in separate messages (forces sequential)
- ❌ Mix tool types in execution messages (breaks parallelism)
- ❌ Read files one at a time across separate messages
- ❌ Create individual TaskCreate calls across separate messages
- ❌ Batch operations that write to the same file
- ❌ Batch operations where B needs A's output
- ❌ Assume all operations can be batched (check dependencies)
Examples
Example 1: Multi-Model Code Review (Batch 5 Reviewers)
Message 1: Preparation
Bash("mkdir -p ai-docs/reviews")
Write("ai-docs/review-context.md", code_context)
Message 2: Parallel Execution (5 Task calls)
Task(security-reviewer) → ai-docs/reviews/security.md
Task(performance-reviewer) → ai-docs/reviews/performance.md
Task(accessibility-reviewer) → ai-docs/reviews/accessibility.md
Task(code-quality-reviewer) → ai-docs/reviews/quality.md
Task(architecture-reviewer) → ai-docs/reviews/architecture.md
ALL 5 execute simultaneously
Message 3: Consolidation
Task(review-consolidator) → ai-docs/consolidated-review.md
Message 4: Present Results
Sequential: 5 * 2 min = 10 min | Batched: ~4 min | 2.5x speedup
Example 2: Codebase Exploration (Batch Searches)
Message 1: Parallel Searches (7 operations, 1 message)
Grep("authenticate") + Grep("authorize") + Grep("jwt|token")
+ Grep("middleware.*auth") + Glob("**/auth*.ts")
+ Glob("**/middleware/**/*.ts") + Glob("**/*.test.ts")
Message 2: Parallel File Reads (all discovered files)
Read("src/auth/authenticate.ts") + Read("src/auth/authorize.ts")
+ Read("src/middleware/auth.middleware.ts")
+ Read("src/services/token.service.ts")
+ Read("src/routes/auth.routes.ts") + Read("tests/auth/auth.test.ts")
Total: 2 messages, ~5 seconds
Sequential: 13 messages, ~30+ seconds | Speedup: 6x+
Example 3: Multi-Phase Workflow (Mixed Batching/Sequential)
Message 1 - Preparation (batch reads + setup):
Bash("mkdir -p ai-docs/feature") + Read("src/existing-module.ts")
+ Read("package.json") + Glob("**/*.test.ts")
Message 2 - Planning (depends on Message 1):
Task(architect) → ai-docs/feature/plan.md
Message 3 - Implementation (3 agents parallel, depends on Message 2):
Task(backend-developer) → src/feature/api.ts
Task(frontend-developer) → src/feature/ui.tsx
Task(test-developer) → tests/feature/
Message 4 - Validation (3 checks parallel, depends on Message 3):
Bash("npm run test -- tests/feature/")
Bash("npm run lint -- src/feature/")
Bash("npm run typecheck")
Message 5 - Review (depends on Message 4):
Task(code-reviewer)
Total: 5 messages (minimum for dependency chain)
Without batching: 10+ messages | Speedup: 2-3x
Troubleshooting
Parallel agents executing sequentially?
Mixed tool types in execution message. Use ONLY Task calls.
File reads arriving one at a time?
Each Read in separate message. Batch all Reads into one message.
Conflicting edits?
Batched Edit calls targeting same file. Sequence same-file edits, batch different-file edits.
Workflow slower than expected despite batching?
Audit dependency chain. Ask at each message boundary: "Does this TRULY depend on the previous one?"
Summary
- The Golden Rule: 1 message = all related operations
- Same tool type in one message enables true parallel execution
- Mixed tool types may force sequential execution
- 3-5x speedup from batching Task launches (biggest impact)
- Up to 10x speedup from batching file reads and searches
- The 4-Message Pattern is the canonical batching template
- Check dependencies before batching (output deps, same-file conflicts)
Master batching and every workflow runs at maximum speed.
Inspired By:
- claude-flow concurrent execution mandate
- 4-Message Pattern from multi-agent-coordination skill
- Production performance analysis of sequential vs parallel workflows
- Claude Code tool execution model observations
