Multi-agent parallel builds

Sparkle runs as many agents at once as you want, and each one works in complete isolation: its own git worktree, its own branch, its own copy of your files. They build at the same time, in parallel lanes that never cross, and their work merges back into your project one change at a time.

The one-line version: don't build serially, build in parallel. Every other tool runs one agent at a time. Sparkle runs a fleet, and you watch the grid.

Three agents colliding in one black terminal on a shared branch (index.lock, merge conflicts) versus Sparkle running them as isolated worker agents, each in its own git worktree and branch, merged back one at a time.

How it works

Each agent Sparkle launches is handed its own worktree: a real, separate folder on your disk, on its own branch, with its own checkout of your code. The agents run side by side, and Sparkle serializes the underlying git operations so they never trip over each other.

Think of it like this. Normally there's one copy of your project on your computer, and one cook in the kitchen at a time, because if two cooks reach for the same pan they collide. A worktree gives every helper its own kitchen, its own copy of all your files, walled off from the others. So you can ask five helpers to work on five different things at once, and none of them can knock over what another one is doing.

A branch is just a safe, named line of work, a snapshot you can change freely without touching the real project until you decide to keep it. Each helper gets its own branch too. When a helper finishes, Sparkle folds its finished work back in for you, one helper at a time, so nothing ever gets scrambled. You never run a command, never juggle folders, never see a conflict. You just describe what you want and watch the work happen in parallel.

Here's the leverage. Spin up one agent on the auth refactor, another on the API rate limiting, a third on the bug in the checkout flow, all at the same moment. They each get an isolated worktree and branch (sparkle/agent-3f2a, -9c1b, -2e7d), so they're not waiting in line behind each other and they're not fighting over your files.

The mental model that makes this pay off: stop thinking "what's my next prompt" and start thinking "what are the three independent chunks of this I can fan out right now." Anything that doesn't depend on another piece can run in its own lane. Sparkle caps how many build agents spawn at once and queues the rest, so you can fire off a fleet without melting your machine, and the finished branches merge back one at a time so you review clean, separable changes instead of one tangled mess.

Mechanically: each agent gets a worktree created outside the project tree (under <app_data>/worktrees/<projectId>/<agentId>) on a branch named sparkle/agent-<id>, cut fresh from origin/main (workers branch from their parent orchestrator's local branch instead). Per-root locking (withRepoLock) serializes git operations across agents sharing a repo, so concurrent worktree adds and commits never race on .git/index.lock. A write-guard keeps each agent confined to its own directory, so an agent literally cannot write outside its lane.

Spawning is bounded: there's a per-build-agent concurrency cap and a spawn queue, so a large fan-out throttles instead of forking bombs. Branches merge back into the orchestrator's branch serially, one at a time, never in a free-for-all. This is git worktree (see the git-worktree docs) put to its proper use: N real local checkouts, zero cross-contamination, no sandbox.

Why it matters

Parallelism is the whole point of directing a fleet. One human can only type into one terminal, but one human can direct many agents at once, and that is a categorically larger amount of work per cycle.

This is what changes how much you can build. You're not limited to one idea at a time anymore. While one agent fixes a bug, another can be adding the feature you've been wanting, and a third can be cleaning something up, all in the same afternoon. You stay in charge of what should happen; Sparkle handles the how of keeping all that work separate and safe. It turns "I have a long list and no time" into "I pointed three helpers at it and went to get coffee."

Serial work is a self-imposed tax. If three tasks don't depend on each other and you're still doing them one after another, you're leaving most of your throughput on the floor. Parallel builds are how a solo builder ships at team velocity: fan out the independent work, let it run, then integrate. Your bottleneck stops being "how fast can I type" and becomes "how clearly can I split the work and review the results," which is exactly the higher-value skill to be spending your time on.

The bottleneck moves up the stack. When generation is cheap and parallel, your constraint is no longer keystrokes, it's how well you decompose work into independent units and how sharply you review the merges. Parallel isolated agents let your judgment scale to a fleet instead of a single keyboard, without giving up real git and real commits on your actual filesystem. The build runs on your Claude Code Max subscription (Pro, Max 5x, or Max 20x: more included usage and more concurrent agents as you go up the tiers).

vs. the 1980s terminal

A terminal is a single serial REPL: one prompt, one cursor, one command at a time, all reading and writing the same working directory. It was built for one human doing one thing, and it is genuinely good at that. It is a terrible foundation for a fleet.

If you tried to do this the old way, you'd be opening a bunch of black terminal windows, all pointed at the same copy of your files, and they'd immediately start overwriting each other's work. There's no built-in way for them to stay out of each other's way. That's why running many helpers used to be an expert-only, error-prone mess. Sparkle takes that whole problem off your plate: the isolation is automatic, so you get the speed of many builders without any of the danger of them colliding.

You've felt this if you've ever tried to run two agents against one repo. They share one working tree, so they stomp the same files and git starts throwing index.lock errors and merge conflicts until you give up. tmux panes don't fix it, they just give you more windows onto the same collision. Sparkle makes the collision impossible instead of asking you to choreograph around it.

One terminal means one working tree and one index. Parallel work in that model means tmux panes all racing on the same .git, which gets you index.lock contention, interleaved output in a single scroll lane, and merge conflicts you created yourself. The "fix" is manual choreography you have to babysit. Sparkle's answer is structural, not procedural: separate worktrees, separate branches, serialized git ops, a write-guard. There's nothing to choreograph because there's nothing shared to collide on.