Raw capture — raw/parallel-coding-agents-guide.md
url: https://superset.sh/blog/parallel-coding-agents-guide date_fetched: 2026-07-05 backfilled: true
Running one AI coding agent is straightforward. Running ten at once introduces problems that most developers haven't encountered before: file conflicts, branch collisions, resource contention, and a review bottleneck that grows linearly with agent count. This guide covers the patterns that work and the mistakes to avoid.
A single coding agent handles one task at a time. You prompt, it works, you review, you iterate. At best, you're doing one unit of agent work per cycle.
But most codebases have dozens of parallelizable tasks at any given time:
These tasks are independent. They can — and should — run simultaneously. The bottleneck isn't the agent or the model. It's the human orchestrating one task at a time.
Running two agents in the same directory creates immediate problems:
This isn't a theoretical risk. It happens every time two agents touch overlapping files. Even if they're editing different files, a shared git index means their commits can include each other's uncommitted changes.
Git worktrees solve this at the filesystem level:
Each worktree has:
They share the git object store, so creating a worktree takes seconds and costs minimal disk space.
The simplest approach — create worktrees yourself and run agents manually:
This works for 2-3 agents but breaks down at scale. You're managing worktrees, branches, and terminals manually.
A shell script that automates worktree creation and agent launching:
Better, but still no unified view of all tasks, no session persistence, and no diff review workflow.
Tools like Superset handle orchestration end-to-end:
This is the approach that scales to 5-10+ concurrent agents without operational overhead.
Different agents have different strengths. A parallel workflow lets you match agents to tasks:
The key insight: you don't have to choose one agent for everything. Run Claude Code on the complex refactor and Codex on the test generation simultaneously.
Parallel agents create a new problem: review throughput. If you run 10 agents and each produces a diff in 15 minutes, you have 10 diffs to review per hour.
Prioritize by risk: A test addition is low-risk and can be reviewed quickly. A database migration is high-risk and needs careful review. Triage diffs by impact.
Review diffs, not files: Don't re-read the entire file. Focus on what changed. If the diff is scoped to what you asked for and the tests pass, a quick review is usually sufficient.
Let agents verify their own work: Before reviewing, check if the agent ran tests. If tests pass and the diff is clean, your review is a sanity check rather than a first-pass audit.
Use structured task descriptions: "Add input validation to the signup form: email must be valid, password must be 8+ characters, display inline errors" produces a reviewable diff. "Improve the signup form" produces something unpredictable.
Batch similar tasks: Review all test additions together, then all refactors. Context switching between different types of changes is the biggest time sink in review.
Each agent consumes local resources for:
On a modern laptop, 5-7 concurrent agents are comfortable. Beyond that, you may want to stagger agent launches or limit concurrent builds.
Each agent makes API calls to its model provider. Running 10 Claude Code instances hits Anthropic's rate limits faster than one. Monitor your provider's rate limit headers and throttle if needed.
Each worktree is a full checkout of your working directory. For a 1GB repo, 10 worktrees use ~10GB. The git object store is shared, so history isn't duplicated. Clean up completed worktrees promptly.
Start with 2-3 until you're comfortable with the review workflow. Scaling to 10 before you can review at speed creates a backlog that slows everything down.
"Fix the bugs" will produce unpredictable results. "Fix the null pointer in UserService.getProfile when user.avatar is null — add a null check and return a default avatar URL" gives the agent exactly what it needs.
If two agents modify the same file on different branches, you'll hit merge conflicts when merging. Plan your task allocation to minimize overlap. If tasks must touch the same files, run them sequentially.
If the agent doesn't run tests, you're reviewing blind. Either include "run tests and fix any failures" in your prompt, or verify tests pass before reviewing the diff.
The goal isn't to run the most agents possible. It's to maximize useful throughput — tasks completed per hour that meet your quality bar. Parallel agents get you there faster than sequential work, but only if the orchestration and review workflow supports it.
How Superset uses Git worktrees to run multiple AI coding agents in parallel without conflicts. A practical guide to the workflow that lets you 10x your throughput.
An attempt to crystallize our plans for 2026
Git worktrees have been around since 2015. For most of that time, they were a curiosity. Now they're having a moment. This is the story of how they came to be and why they suddenly matter.