What does Claude Code's bundled `/batch` skill do with a codebase-wide change, and why might its workers miss your unpushed commits?
answer
- a skill, not fixed logic
- research, split, plan, approve
- five to thirty independent units
- one isolated worktree per worker
- worktrees branch from the remote default
basics
~20 sClaude Code's /batch splits a large change into 5 to 30 independent units and, after you approve the plan, runs one background subagent per unit in its own worktree, branched from the remote default branch unless worktree.baseRef is head.
solid answer
~40 s`/batch <instruction>` is a **bundled skill**, so it is a prompt that has Claude orchestrate the work with its tools rather than fixed logic. It researches the codebase, decomposes the change into 5 to 30 independent units and presents a plan; after you approve, it spawns one background subagent per unit, each in an isolated worktree, and each implements its unit, runs the tests and publishes its change. It needs a git repository or a `WorktreeCreate` hook that creates the worktrees. Workers miss your unpushed commits because worktrees Claude Code creates for subagents follow the same base rule as `--worktree`: they branch from the repository's default branch on the remote unless `worktree.baseRef` is `"head"`. Push or commit first, or set `"head"`; uncommitted edits never travel either way.
go deeper
Recall that /batch is a bundled skill for large changes: it plans, then runs one worker per unit in its own worktree.
Explain the steps, research, 5 to 30 units, approval and parallel worktree subagents, and why the worktrees lack unpushed or uncommitted work by default.
Show the operational setup: commit and push or set baseRef to head, .worktreeinclude and dependencies for tests, a WorktreeCreate hook outside git, and a plan review that removes overlapping units.
Weigh thirty parallel changes against review and merge capacity, and decide when a sequential session or a coordinated team is the cheaper way to land the change.
## What `/batch` is Claude Code ships some **bundled skills**: prompt-based instructions that Claude follows with its normal tools, unlike most built-in commands, which run fixed logic. `/batch` is one of them, built for **large-scale changes across a codebase** such as migrating a source tree from JavaScript to TypeScript or replacing a deprecated API everywhere. The documentation describes it as a packaged use of subagents and worktrees, not a separate coordination style. ## What happens when you run it ``` /batch migrate src/ from JavaScript to TypeScript ``` 1. **Research**: Claude reads the codebase to understand the change's scope. 2. **Decompose**: it splits the work into **5 to 30 independent units**. 3. **Plan**: it presents the plan and waits; nothing is edited until you approve. 4. **Fan out**: it spawns one **background subagent per unit**, each in an **isolated worktree**. 5. **Deliver**: each subagent implements its unit, runs the tests and publishes its change. Because each unit lives in its own worktree, the workers cannot overwrite each other's files or your checkout, and the worktree isolation checks block them from reaching back into the main checkout. ## Requirements | Situation | What `/batch` needs | |---|---| | inside a git repository | nothing extra; Claude Code creates the worktrees with git | | outside git (SVN, Perforce, Mercurial and so on) | a `WorktreeCreate` hook that creates each working copy, and Claude Code 2.1.281 or later | Outside git, with a hook, each subagent publishes its change using your project's version-control commands and, when it cannot open a pull request, reports what it published instead. ## Why the workers miss your unpushed work The worktrees Claude Code creates for subagents use the **same base rule** as `claude --worktree`, set by `worktree.baseRef`: - **`"fresh"` (default)**: branch from the repository's default branch on `origin`. Commits you have not pushed, and your feature branch's state, are absent. - **`"head"`**: branch from your current local `HEAD`, the documented choice when isolated subagents must operate on in-progress work. Either way a worktree is built from a commit, so **uncommitted edits** in your checkout never reach the workers. Before a big `/batch` run on a feature branch: commit, then push or set `"head"`. The usual fresh-checkout gaps apply too: - gitignored configuration such as `.env` needs a `.worktreeinclude` file (or copying inside your `WorktreeCreate` hook); - dependencies must be installed or linked with `worktree.symlinkDirectories` before tests can run. ## When it fits, and when it does not - **Fits**: a change that splits into independent pieces with a clear per-piece test, such as a per-module migration or a mechanical API swap. - **Poor fit**: tightly coupled work where units must see each other's edits; independent worktrees mean one unit's change is invisible to the next until merged. - **Different tool**: if workers must discuss and divide work dynamically, that is what experimental agent teams are for, at the cost of no worktree isolation between teammates. ## Preparing a run 1. **Fix the base**: commit and push what the units must build on, or set `worktree.baseRef` to `"head"`. 2. **Make a fresh checkout testable**: `.worktreeinclude` for gitignored configuration, and a plan for dependencies, so each worker's test run means something. 3. **Scope the instruction**: name the directory or pattern and the condition that counts as done. 4. **Read the plan before approving**: merge units that overlap, and pull shared edits into a single unit. ## Cost and review Up to thirty parallel subagents multiply token use against one sequential session, and the result is up to thirty published changes for someone to review and merge. Review the plan carefully at step 3: a bad decomposition, units that overlap or depend on each other, is cheaper to fix there than across thirty branches. Workers that finish without changes leave temporary worktrees that Claude Code removes; worktrees with changes stay until a later sweep can remove them without losing work.
- Two `/batch` units both need to edit a shared configuration file. What goes wrong, and what do you do at the plan step?Each unit edits its own worktree, so both changes are made independently and only collide when you merge them, as conflicting branches. Reject or adjust the plan so one unit owns the shared file, or make the shared change first, commit it and let the units build on it.
- Why is `/batch` called a skill rather than a built-in command, and does that matter?Bundled skills are prompt-based: they give Claude detailed instructions and let it orchestrate the work with its tools, while most built-in commands run fixed logic. It matters because the decomposition is Claude's judgment, which is why `/batch` stops to present a plan for your approval before spawning anything.
- /batch is a fixed built-in command that runs the same steps regardless of the codebase.
- /batch starts editing files straight away without showing a plan.
- /batch applies its units one by one in your current checkout.
- /batch workers coordinate through an agent team's shared task list.
- /batch sees your uncommitted edits because its workers start from your checkout.
Assumes Claude Code 2.1.286; running /batch outside a git repository, with a WorktreeCreate hook, requires 2.1.281 or later.