Batch: Parallel Agent Execution
/batch fans out a large task across multiple parallel Claude Code agents, each working in its own git worktree. Instead of one agent working through 200 files sequentially, ten agents tackle 20 files each — simultaneously.
For large migrations, sweeping refactors, or any task where the work is naturally divisible, batch execution collapses hours into minutes.
How Batch Divides Work
When you run /batch, Claude Code:
- Analyzes the task and identifies the natural unit of division (files, modules, directories, feature areas)
- Splits the work into N chunks based on the
--agentscount or automatic sizing - Creates a git worktree for each agent (isolated branch, no file conflicts)
- Dispatches each agent with its specific chunk and shared context
- Monitors progress across all agents
- Merges results back to the main branch when all agents complete
Each agent runs independently. An agent working on src/components/ has no awareness of the agent working on src/api/. They share only the base branch state at dispatch time.
Dependency on Git Worktrees
/batch requires git worktrees. Each agent gets its own worktree — a separate checkout of the repository at a fresh branch — so agents can write files without stepping on each other.
# Claude Code manages worktrees automatically during /batch# But you can inspect them:git worktree list
# Output during a batch run:# /Users/you/project abc1234 [main]# /tmp/claude-batch-a1 def5678 [batch/agent-1]# /tmp/claude-batch-a2 ghi9012 [batch/agent-2]# ...Worktrees are created at batch start and deleted after the merge step. If a batch fails mid-run, worktrees remain so you can inspect agent state.
Note: Your repository must be a git repo. Bare repositories and shallow clones are not supported.
Execution: Linear vs Parallel
Syntax
# Basic batch — Claude auto-sizes agent count/batch "[task description]"
# Explicit agent count/batch --agents 10 "[task description]"
# Batch with a specific file list/batch --files "src/**/*.ts" "[task description]"
# Dry run — shows the split plan without executing/batch --dry-run "[task description]"
# Monitor a running batch/batch --status
# Cancel a running batch (agents finish current file, then stop)/batch --cancelExample: Migrate 50 Files to New API
Your team is moving from a deprecated fetchData() utility to a new apiClient.get() pattern. 50 files need updating.
/batch --agents 5 "migrate all usages of fetchData() to apiClient.get(). The new signature is apiClient.get(url, options) where options is an object. fetchData took positional args: fetchData(url, method, body). Preserve all error handling. Run the tests for each file after migrating it."Claude Code:
- Finds all 50 files containing
fetchData( - Splits into 5 groups of 10 files
- Dispatches 5 agents, each migrating their 10 files and running tests
- Merges all 5 branches back to main once all agents pass tests
Total time: roughly the time to migrate 10 files, not 50.
Example: Large Refactor Across 200 Files
Rename a core domain concept — say, User to Account — across 200 source files, with type checking after each file.
/batch --agents 10 --files "src/**/*.ts" "rename the domain concept 'User' to 'Account' throughout. This includes: type names, interface names, variable names where context is clearly about the domain entity (not generic 'user' variables in UI code). After each file, run tsc --noEmit to verify no type errors were introduced. Do not rename 'currentUser' variables in React components — those are UI state, not domain entities."The nuanced instruction (“do not rename currentUser in React components”) is passed to every agent. Each agent applies the same judgment independently.
Boris’s Workflow
Boris uses /batch for large migrations that would otherwise take a full day of mechanical work:
-
API version upgrades: When a major library releases a breaking change, batch dispatches one agent per directory. Each agent updates imports, adjusts call sites, and verifies types. Boris reviews the consolidated diff rather than doing the migration himself.
-
Codebase-wide lint rule enforcement: Enabling a new ESLint rule across a large codebase produces hundreds of auto-fixable violations. Batch handles the auto-fixes in parallel; Boris reviews only the files the agents flagged as needing human judgment.
The pattern: anything that is large, repetitive, and has a clear mechanical transformation is a batch candidate.
Gotchas
Merge Conflicts
If two agents modify the same file (e.g., a shared utility both need to update), their changes will conflict at merge time. Prevention strategies:
- Use
--filesto give Claude Code explicit, non-overlapping file sets - Describe shared files in the task prompt: “Do not modify
src/utils/shared.ts— I will update that separately” - Run
--dry-runfirst to inspect how Claude intends to split the work
When conflicts do occur, Claude Code surfaces them as a list of files needing manual resolution before the merge completes.
File Ownership
Each agent owns its assigned files for the duration of the batch. Agents do not communicate with each other mid-run. If agent 1 adds a helper function that agent 2 also needs, agent 2 will not see it — they work from the same base branch snapshot.
Design tasks so each chunk is self-contained. If agents need to share a new abstraction, add it to the base branch first, then run the batch.
Token Consumption
Ten agents running in parallel consume ten times the tokens of a single agent. For large batches on large files, this adds up quickly. Use --dry-run to preview the scope before committing.
Partial Failures
If some agents succeed and some fail, the successful agents’ branches are preserved. You can inspect the failures, fix the issues, and re-run /batch with --resume <batch-id> to retry only the failed chunks.