Full Refactor Taking Days? /batch Splits Big Changes in Parallel

A "full overhaul" like swapping out a whole library or adding validation code to every API. Once you actually start, it takes days, and the volume is a mountain you can't even bring yourself to face. Fixing one at a time by hand, you also lose track of how far you've gotten. /batch is the command for these large-scale jobs. It splits a big change into dozens of pieces and processes them simultaneously, shrinking a days-long job to hours. It's an advanced feature, so at the beginner stage, knowing "this exists" is enough.

Definition

/batch is a command that splits a big change into units of 5-30 and processes them in parallel.

Let's note two key concepts.

• Parallel processing: A way of finely dividing work and running multiple pieces simultaneously. Instead of one person doing it in sequence, it's like many workers each taking one piece and working at the same time.
• worktree: An isolated workspace where each piece works. Each piece works in a separately partitioned room, so one piece's change doesn't break another.

And each piece, on finishing its work, even makes a PR (Pull Request, a request to merge the changes). In other words, "split → simultaneous work → each submits a PR" flows automatically.

How to use it (by difficulty)

Basics — entrust a large-scale change

Write the change scope and content in the chat box.

/batch convert the src/ folder from Solid to React

On entering it, Claude divides this big job into several pieces, then runs each piece simultaneously in an isolated space. The screen shows each piece's progress, and when done, each change is organized as a PR.

Applied — assign by specifying scope

/batch add input validation logic to every API endpoint

"Repeated work spanning the whole codebase" can be divided up too. Splitting the job of putting the same validation into dozens of APIs into pieces and processing them simultaneously is far faster than touching them one by one.

Common pitfall — don't merge results all at once; review first

/batch's strength is speed, but with it comes a caution point. Merging the PRs made by multiple pieces all at once without review is dangerous.

• Because each piece works separately in an isolated space, changes that conflict with each other or are inconsistent can arise.
• So after batch finishes, it's safe to review each PR's changes (e.g., with /diff) and merge them one by one.

As much as it builds fast, remember that the review before merging is the human's job. Rather than using it on a large codebase right away at the beginner stage, I recommend testing once on a small scope.

A real case

There was a migration job to move an old library entirely to a new version. By hand it would've been a days-long thing. With /batch I split the work into 30 units and ran them simultaneously.

/batch migrate the whole project's old library version to the new version

Each piece ran simultaneously in an isolated space and produced PRs, and I reviewed and merged the PRs one by one. A major overhaul that would've taken days in sequence finished in far less time.

Use it like this too

• Break into 5-30 pieces: Split a big change into independent units and process them simultaneously.
• Isolated execution + PR: Each piece works separately and submits its result as a PR.
• Large-scale migration: Suited to major overhauls like library swaps or framework conversions.
• Progress management: As many pieces run, it's good to watch and manage the progress.

Tip: As powerful as /batch is, the risk is just as big. At first, test on one small folder, build the habit of always reviewing the resulting PRs, and then expand to a larger scope.

Wrap-up

The key is one sentence. A major overhaul that would take you days alone — split it and process it simultaneously with /batch. You can have big changes divided up automatically, so even a full refactor or migration can finish fast. But as fast as it is, the review before merging must always be handled by a human.

Based on: Claude Code v2.1.154 (2026.05)