{"slug": "how-i-run-4-claude-code-agents-in-parallel-on-one-repo-without-chaos", "title": "How I Run 4 Claude Code Agents in Parallel on One Repo Without Chaos", "summary": "A developer has described a workflow for running up to four Claude Code agents in parallel on a single repository by giving each agent its own git worktree, a scoped task contract, and a serial merge queue. The approach uses git worktrees for isolation, non-overlapping file ownership maps for decomposition, and a merge queue for integration, turning a week of sequential refactoring into an afternoon. The developer notes that a naive first attempt with four agents in the same working directory collapsed within 40 minutes when one agent committed another's half-finished changes.", "body_md": "I run up to four Claude Code agents at the same time on a single repository by giving each one its own git worktree, a tightly scoped task, and a merge queue at the end. Done right, parallel agents turned a week of sequential refactoring into an afternoon. Done wrong (I did it wrong first), you get four agents editing the same file and a merge disaster that eats every minute you \"saved.\" Here's the setup, the failure modes, and the rules I follow now. 🚀\n\nOne Claude Code session is great. But last quarter I stared at a backlog that was embarrassingly parallel:\n\nNone of these tasks depended on each other. Running them one at a time through a single agent session meant babysitting my terminal for days, mostly watching an agent do work that didn't need my attention.\n\nThe obvious idea: run four agents at once. The obvious problem: they'd all be working in the **same working directory**. Two agents running `npm test` simultaneously clobber each other's build artifacts. Two agents editing neighboring lines of the same barrel file produce garbage. One agent runs `git checkout` mid-task and yanks the floor out from under the other three.\n\nMy first naive attempt — four terminal tabs, same directory, \"they probably won't collide\" — lasted 40 minutes before agent #2 committed agent #3's half-finished changes along with its own. I reverted everything and started over with an actual design.\n\nThe fix has three parts: **isolation** (git worktrees), **decomposition** (non-overlapping task contracts), and **integration** (a serial merge queue). I'm on Claude Code v2.x and git 2.44 here, but nothing below is version-sensitive.\n\nGit worktrees are the underrated feature that makes this whole thing work. A worktree is a second (third, fourth...) checkout of the same repository that shares one object database but has its own working directory, its own index, and its own checked-out branch:\n\n```\n# From the main checkout\ngit worktree add ../repo-agent-1 -b agent/validation-migration\ngit worktree add ../repo-agent-2 -b agent/jsdoc-pass\ngit worktree add ../repo-agent-3 -b agent/logging-swap\ngit worktree add ../repo-agent-4 -b agent/characterization-tests\n```\n\nNow each agent gets launched with its **own directory as the working root**:\n\n```\ncd ../repo-agent-1 && claude \"Migrate the API handlers in src/api/ to zod validation. Task spec is in TASK.md.\"\n```\n\nEach agent can run tests, install dependencies, create commits, even make a mess — and the other three never see it. No shared index, no shared working tree, no `git checkout` rug-pulls. The failure mode from my naive attempt is structurally impossible.\n\nTwo practical notes that bit me:\n\n`node_modules`. Either let each agent install its own (slow, safe) or symlink from the main checkout (fast, occasionally cursed when an agent modifies a lockfile). I install fresh. The 90 seconds of `npm ci` per worktree is nothing next to debugging a shared-`PORT=3001`, `PORT=3002`, ...) and a scratch database name in its task spec.\nIsolation stops agents from stepping on each other's *working directories*, but it doesn't stop them from editing the *same logical files* — which just moves the collision from runtime to merge time. Way better, still bad.\n\nSo every parallel task gets a short **task contract** — a `TASK.md` dropped into the worktree before the agent starts:\n\n```\n# Task: Replace deprecated log.info() calls\n\n## You own (may edit):\n- src/**/*.ts EXCEPT src/api/** and src/shared/logger/**\n\n## You must NOT touch:\n- src/api/**            (owned by agent-1 this session)\n- package.json, any lockfile\n- CI config\n\n## Definition of done:\n- `grep -r \"log.info(\" src` returns 0 hits outside src/api\n- `npm test` passes\n- Work is committed on this branch with a descriptive message\n```\n\nThe load-bearing part is the **ownership map**. Before launching anything, I spend ten minutes deciding which agent owns which paths, and the union must be disjoint. If two tasks genuinely need the same file, they don't run in parallel — one of them waits. That sounds obvious written down; it took a mangled merge for me to actually start doing it.\n\nShared \"junction\" files (barrel exports, route tables, config) deserve special paranoia. My rule: **no agent touches a junction file during a parallel session.** If a task needs a new export added to an index file, the agent leaves a note in its final commit message and I do the two-line edit myself during integration.\n\nParallel work, serial integration. When agents finish, I never merge branches simultaneously or in arbitrary order. The flow is:\n\n``` php\ngraph LR\n    A[agent/validation] --> Q{merge queue}\n    B[agent/jsdoc] --> Q\n    C[agent/logging] --> Q\n    D[agent/tests] --> Q\n    Q -->|one at a time| I[integration branch]\n    I -->|full CI green| M[main]\n```\n\nConcretely:\n\n`integration` branch, run the full test suite.`main` only ever receives Step 3 matters more than it looks. Each agent validated its work against the repo *as it was when the session started*. After the first merge, that assumption is stale. The rebase-and-recheck catches interactions — like the validation migration changing an error message format that the new characterization tests had snapshotted. If the ownership map was truly disjoint, rebases are conflict-free and this whole phase is 20 minutes of watching CI. When it's not conflict-free, that's a signal my decomposition was wrong, and I treat it as a lesson for next session's ownership map, not as a merge problem to power through.\n\nMy end-to-end loop for a four-agent afternoon:\n\n```\n# 1. Decompose: write four TASK.md files, check ownership is disjoint\n# 2. Spin up worktrees + branches (script does this in ~10s)\n./scripts/spawn-worktrees.sh validation jsdoc logging tests\n\n# 3. Launch agents, one terminal tab each, non-interactively\ncd ../repo-validation && claude -p \"$(cat TASK.md)\" &\n\n# 4. Check in every ~20 min; answer questions, unstick anyone stuck\n# 5. Integration: merge queue, one branch at a time\n# 6. Tear down\ngit worktree remove ../repo-validation  # etc.\ngit worktree prune\n```\n\nWhile agents run, I do interrupt-driven supervision instead of continuous babysitting: glance at each tab, unstick whoever's stuck, and otherwise do my own work. Four tasks that would have serialized into roughly four days of elapsed time landed in `main` the same evening.\n\n**Parallelism amplifies your decomposition skills — in both directions.** With a clean ownership map, four agents ≈ 3.5x throughput. With a sloppy one, four agents produce merge conflicts faster than one agent produces code. The ten minutes of upfront path-ownership planning is the highest-leverage ten minutes of the whole session.\n\n**Worktrees beat clones, and both beat shared directories.** Full `git clone` s per agent also work but waste disk and drift from your local branches. Worktrees share the object store, so they're near-instant to create and trivially cheap. Shared directories are not an option; don't let \"it's just two quick tasks\" tempt you.\n\n**Four is my ceiling, and the bottleneck is me.** Agents don't get slower with more parallelism — *supervision* does. Each additional agent adds another stream of questions, another integration branch, another definition-of-done to verify. At five or six I stop actually reviewing and start rubber-stamping, which defeats the point. Your ceiling might differ; you'll know you've passed it when you stop reading diffs.\n\n**Not every backlog is parallel.** I now sort tasks into \"embarrassingly parallel\" (mechanical migrations, test backfills, doc passes — disjoint by nature) and \"inherently serial\" (anything touching core abstractions that everything else imports). Forcing serial work into parallel sessions is how you end up re-doing three branches after the fourth changes the interface they all depend on.\n\n**Make agents commit early and often on their own branch.** My task contracts require a commit at every meaningful checkpoint. When an agent goes sideways (one decided mid-task to \"improve\" an unrelated module ⚠️), `git log` on its branch tells me exactly where the plot was lost, and I reset to the last good commit instead of restarting the whole task.\n\nTwo things I'm actively experimenting with:\n\n`watch cat status.log` replaces tab-hopping. Interrupt-driven supervision is good; glanceable supervision would be better.\nRunning agents in parallel isn't a Claude Code feature you turn on — it's a workflow you design. Isolate with worktrees, decompose with explicit ownership, integrate serially. Get those three right and the multiplier is real.\n\nIf you've built your own multi-agent setup — especially if you've pushed past four agents without losing the plot — I'd genuinely love to hear how you handle integration. Drop a comment 👇, and **follow me here on Dev.to** for more write-ups on running AI coding agents against real codebases. ✅", "url": "https://wpnews.pro/news/how-i-run-4-claude-code-agents-in-parallel-on-one-repo-without-chaos", "canonical_source": "https://dev.to/yureki_lab/how-i-run-4-claude-code-agents-in-parallel-on-one-repo-without-chaos-5ejc", "published_at": "2026-09-11 14:32:06+00:00", "updated_at": "2026-09-11 14:45:20.630899+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["Claude Code", "Anthropic", "git"], "alternates": {"html": "https://wpnews.pro/news/how-i-run-4-claude-code-agents-in-parallel-on-one-repo-without-chaos", "markdown": "https://wpnews.pro/news/how-i-run-4-claude-code-agents-in-parallel-on-one-repo-without-chaos.md", "text": "https://wpnews.pro/news/how-i-run-4-claude-code-agents-in-parallel-on-one-repo-without-chaos.txt", "jsonld": "https://wpnews.pro/news/how-i-run-4-claude-code-agents-in-parallel-on-one-repo-without-chaos.jsonld"}}