Claude Code /batch: split one large change across parallel agents

Last updated: November 9, 2026

TL;DR

Claude Code's /batch is a bundled skill for one large change that runs across a codebase. Type /batch with an instruction, and Claude researches the code, splits the work into 5 to 30 independent units and shows you a plan. Once you approve it, each unit gets its own background subagent in an isolated git worktree, which makes the change, runs the tests and opens a pull request or reports what happened.

• 🧰 Before you start. A git repository, your work pushed, gitignored files listed in .worktreeinclude, and gh or glab signed in.
• ✍️ Write the instruction. One change, one scope, one way to check it.
• 🗺️ Read the plan. Nothing runs until you approve it, so this is where you catch units that overlap.
• 🏃 Let it run. Answer permission prompts in your main session and watch progress with /tasks.
• 🔍 Review the pull requests. One per unit, each reviewed on its own.
• 🧹 Clean up. Worktrees with no changes go on their own. The rest wait for a sweep or git worktree remove.
• 🚫 Pick another tool when it fits better. Small edits, research and unrelated tasks each have a better fit.

If you searched for Anthropic's Message Batches API, it's a different product: the section on it below has the short version.

Before you start

/batch arrived as a bundled slash command in Claude Code 2.1.63, according to the Claude Code changelog. Five things decide whether a run goes smoothly:

1. A git repository. Each unit runs in its own worktree, so /batch needs git, or a WorktreeCreate hook that creates worktrees for another version control system (covered below).
2. Your work pushed, or the base set to your branch. Subagent worktrees branch from your repository's default branch on the remote, usually main, so unpushed commits on a feature branch won't be in them. Push first, or set worktree.baseRef to "head" in your settings so new worktrees start from your current HEAD.
3. Gitignored files listed. A worktree is a fresh checkout with tracked files only. Add a .worktreeinclude file at the project root, in .gitignore syntax, that lists .env and anything else your tests need. Claude Code copies matching gitignored files into every subagent worktree it creates with git.
4. Tests that run from a clean checkout. Each subagent runs the tests on its own unit. If your test command needs a setup step, that step has to work inside a brand-new worktree too.
5. A pull request CLI signed in. Anthropic's common workflows guide names gh pr create on GitHub and glab mr create on GitLab as the commands Claude uses to create pull requests. Sign in to the one you use before you start.

Step 1: Write the instruction

Type /batch followed by the change you want. This is the example in Anthropic's commands reference:

/batch migrate src/ from JavaScript to TypeScript

Claude researches and splits whatever you write, so give it three things:

• One change. A rename, a migration, a pattern swap. Two unrelated changes in one instruction produce units that depend on each other.
• A scope. A directory, a package or a file pattern, so the plan stays inside the code you meant.
• A check. The test or build command that proves a unit is done, for example "each unit passes npm test".

A fuller instruction reads like this:

/batch replace every call to the old logger in packages/ with the new logger from packages/log, keep the log levels the same, and make each unit pass npm run test in its own package

Step 2: Read the plan before you approve it

Claude edits nothing at first. It researches the codebase, splits the change into 5 to 30 independent units and presents a plan. Approval is what starts the parallel work, so read the plan for three things:

If the split is wrong, don't approve it and patch it later. Reply with what to change and read the new plan.

Step 3: Approve the plan and answer the prompts

Once you approve, Claude Code starts one background subagent per unit, each in its own worktree. Each subagent implements its unit, runs the tests, and then opens a pull request or reports what happened.

Background subagents run while you keep working, and their permission prompts come to you. When one reaches a tool call that needs permission, Claude Code shows the prompt in your main session and names the subagent asking. Approve to let it continue, or press Esc to deny that one call without stopping the subagent. A choice that lasts beyond one call, such as a grant for the rest of the session, applies to the whole session, your main conversation included.

With up to 30 units, the same prompt can arrive many times. An allow rule in your permission settings approves a matching command without asking. Swap in your own test command:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)"
    ]
  }
}

Step 4: Check on the units while they run

Run /tasks to see the session's background work. It lists each item and lets you check on, attach to or stop it, and Claude Code runs it straight away even while Claude is mid-response.

A subagent that finishes stays in /tasks, marked done, for 30 seconds. Press Enter on it in that window to open its transcript. A subagent that fails or that you stop leaves the list. Claude reports a background subagent's results once its completion notification arrives, so if you ask about a unit before then, Claude tells you it's still running.

Step 5: Review each pull request on its own

Every unit that finishes ends as its own pull request, so a 20-unit run becomes 20 small reviews instead of one huge diff. Review and merge them like any other pull request. A unit that couldn't open one reports what happened in your session instead.

If merging the first few pull requests causes conflicts in the rest, two units touched the same code. That's the overlap the plan check in step 2 is there to catch.

Step 6: Clean up the worktrees

Claude Code removes a subagent's worktree automatically when the subagent finishes without changes. A worktree with changes stays on disk until a periodic sweep can remove it without losing work. The sweep removes subagent worktrees older than your cleanupPeriodDays setting, 30 days by default, and leaves any worktree that still holds changed or untracked files or unpushed commits.

To clear them sooner:

git worktree list
git worktree remove <path from the list>

Add -f to git worktree remove for a worktree with uncommitted changes or untracked files, once you're sure nothing in it is needed. Our Claude Code worktrees guide covers the rest of worktree cleanup and its errors.

Run /batch outside a git repository

Since Claude Code 2.1.281, /batch also runs where a WorktreeCreate hook provides the worktrees, for SVN, Perforce, Mercurial or another system. Each subagent then publishes its change with your project's version-control commands, and when it can't open a pull request, it reports what it published.

The hook replaces git's worktree logic, so .worktreeinclude isn't processed. Copy local config files inside the hook script instead. Anthropic's worktrees guide has an example SVN hook and points to the matching WorktreeRemove cleanup.

When /batch is the wrong tool

/batch is a packaged use of subagents and worktrees, not a separate way of coordinating agents, as Anthropic's guide to running agents in parallel puts it. Use it for one large change that splits into independent pieces. For other jobs:

Our guide to how to run Claude Code agents in parallel compares those options side by side.

/batch vs the Message Batches API

They share a word and nothing else. The Message Batches API is part of Anthropic's API: you send a large volume of Messages requests that don't need an immediate answer, and it processes them asynchronously at 50% lower cost. Most batches finish within an hour. Results are available once every message completes or after 24 hours, whichever comes first, and a batch expires if processing doesn't finish within 24 hours.

The Message Batches API doesn't edit code, open pull requests or touch your repository. /batch is the Claude Code skill this guide covers.

Settings that change a /batch run

Frequently asked questions

What does /batch do in Claude Code?

/batch is a bundled skill for one large change across a codebase. Claude researches the code, splits the work into 5 to 30 independent units and presents a plan. After you approve it, each unit gets a background subagent in its own git worktree that implements the unit, runs the tests and opens a pull request or reports back.

How do I use /batch in Claude Code?

Type /batch followed by one change, a scope and a way to check it, such as /batch migrate src/ from JavaScript to TypeScript. Read the plan Claude presents, approve it, answer permission prompts in your main session, then review the pull request each unit opens.

How many agents does /batch run?

One background subagent per unit, and Claude splits the change into 5 to 30 units. Claude Code also caps how many subagents Claude can have running at once from its Agent tool, 20 by default, and the CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS environment variable changes that cap.

Does /batch need a git repository?

It needs git or a WorktreeCreate hook that creates the worktrees. Outside a git repository, /batch requires Claude Code 2.1.281 or later, and each subagent publishes its change with your project's version-control commands, reporting what it published when it can't open a pull request.

Why are my unpushed changes missing from the /batch worktrees?

Subagent worktrees branch from your repository's default branch on the remote unless worktree.baseRef is set to "head". Push your branch first, or set "head" so new worktrees start from your current HEAD with its unpushed commits.

Is /batch the same as the Message Batches API?

No. The Message Batches API processes large volumes of API requests asynchronously at 50% lower cost, with most batches done within an hour and a 24-hour limit. /batch is a Claude Code skill that changes your codebase through parallel subagents and opens pull requests.

Can I turn off /batch?

Yes. Add "batch": "off" under skillOverrides in your settings to hide it from Claude and the / menu, or set disableBundledSkills to true to turn off every bundled skill, /batch included.

What happens to the worktrees after /batch finishes?

Claude Code removes a subagent's worktree when the subagent finishes without changes. Worktrees with changes stay until a periodic sweep removes them after cleanupPeriodDays, 30 by default, and the sweep skips any that still hold uncommitted or unpushed work. Remove one sooner with git worktree remove.

Give every unit the same project rules

Each /batch subagent starts with the instruction files from your main conversation, not from its own worktree. Thirty units read one set of project rules, so the rules you've written down decide how consistent the thirty pull requests come out. Our guide to compound engineering for Claude Code shows how to build those rules up one fix at a time, so the next large change inherits every lesson from the last.