How /batch Works

Save to .claude/commands/batch.md:

---
description: Run a migration across files in parallel git worktrees
argument-hint: <migration prompt> [--chunk-size N] [--filter <glob>]
---

You will split a large mechanical migration across parallel worktrees.

1. Parse `$ARGUMENTS`:
   - Migration prompt (required, free text)
   - `--chunk-size N` (default 10)
   - `--filter <glob>` (default: derive from prompt — e.g. "all .js" -> `**/*.js`)

2. Discover the file set with `git ls-files <filter>`. If empty, stop and report.

3. Split into chunks of N files. For each chunk i:
   - Create branch `claude/batch-<task-id>-<i>` from current HEAD.
   - Create worktree at `.worktrees/batch-<task-id>-<i>`.
   - Spawn an Agent (subagent_type=general-purpose) with this prompt:
     ```
     Apply this migration to ONLY these files: <chunk file list>.
     Migration: <user prompt>.
     Run the project's typecheck and lint after each file.
     Commit at the end with message: "batch <i>: <prompt summary>".
     If any file errors out, leave it unchanged and report the path.
     ```

4. Wait for all chunks to complete. Collect their final commit SHAs and any error reports.

5. Print summary:

/batch summary

Chunks: N (parallel) Files migrated: M Errors: K (paths listed) Branches created: claude/batch--1 .. -N Next: review per branch, merge OR open one PR each.

## Boundaries

- Never run /batch on a dirty working tree (uncommitted changes). Stop and ask.
- Never auto-merge the chunk branches into main — leave PRs to a human decision.
- Cap parallel chunks at 8 (resource ceiling); if N > 8, reduce automatically and warn.
- Clean up worktrees only after user confirms ("Clean up batch worktrees?"). Never auto-rm.

Why worktrees, not branches?

A worktree gives each subagent its own filesystem checkout. Subagents can run npm install, tsc, etc., without colliding. Pure-branch approach (single working dir) serializes those steps.

Example session

You:    "/batch 'Replace all moment() with date-fns' --chunk-size 8"
Claude: -> ls-files: 47 files import moment
        -> 6 chunks of ~8 files
        -> 6 worktrees + 6 subagents in parallel
        -> ~14 minutes later: all 6 chunks committed
        -> Summary: 47 files migrated, 0 errors, 6 branches ready
        -> Next: open one PR per chunk OR rebase all into one branch

FAQ

Q: How does this differ from a regular shell xargs -P codemod? A: Each chunk is run by a Claude subagent that can handle non-mechanical edge cases (e.g. moment.js APIs without 1:1 date-fns equivalents). Pure codemods can't do that.

Q: Will it auto-merge? A: No. It opens branches; merge decisions stay with you.

Q: What if the migration breaks tests? A: The chunk-level prompt runs typecheck + lint after each file. Test runs are at your discretion in the worktree.

Q: How many chunks max? A: Capped at 8 to avoid resource exhaustion. Edit the cap in the command file.

Q: Is this Boris's actual /batch? A: No — community-written equivalent based on his public description.