Git Worktree Workflow for Concurrent Feature Development

A feature branch stalls out the moment production breaks or a teammate asks for a quick review, and most developers still handle that interruption the way they did a decade ago: commit something half-finished, stash it and hope, or clone the whole repo again. All three are workarounds for a problem git worktree already solved. Of the three, stashing is a common reflex, even though it becomes the worst choice once an AI agent is the one doing the interrupted work. Worktree gives each branch its own working directory on disk, while every one of those directories shares a single object store underneath, so switching tasks stops requiring a git operation at all. That's the argument here, and the rest of this piece covers setup, structure, and running the thing at scale, including inside AI agent workflows where a context switch now costs tokens, not just attention.

Take the interruption itself. Committing half-finished work to get out of the way leaves a broken state sitting on a shared branch, which someone else might pull before it's fixed. Stashing avoids that, but only defers the pain: popping a stash after a teammate has pushed several commits upstream produces conflicts that routinely take longer to untangle than the original interruption did. That makes stashing a worse habit than it looks, not a safer one. Cloning the repo a second time sidesteps both problems but doubles disk usage immediately, and the two clones drift apart in local config and remote tracking until nobody's sure which one holds the real state of anything.

None of that accounts for the actual cost, which isn't mechanical. Research on interruptions puts the average time to get back to a task after an interruption at around 23 minutes, and every one of the three escape routes forces that interruption whether or not the task was ready to be interrupted. With AI coding agents now doing large chunks of implementation work, the cost compounds: a session that's built up real context about a codebase over many tool calls loses that context the moment something forces a branch switch, and restarting it costs time a second time.

Git has shipped a native fix for this for over ten years. Worktree support has been in the CLI a long time. What's been missing until recently is IDE support good enough that developers didn't have to drop into a terminal to use it, and that gap, not any weakness in the feature itself, is the real reason adoption lagged.

What git worktree actually does under the hood

A git repository has exactly one object store: one place where every commit, branch, tag, and blob actually lives. Worktree doesn't touch that. What it adds is a second, or third, or twentieth, directory on disk, each with its own checked-out branch and its own index, all pointing back at that same shared store.

Make a commit in one worktree and it shows up instantly in every other worktree tied to that repository, because there's only one history to show up in. The separation sits at the level of working files, not history, which is exactly why worktrees are cheap: adding one doesn't duplicate the repo's commit history at all. The added disk cost is just the checked-out files plus a small metadata stub Git writes into .git/worktrees/.

One constraint trips people up early: Git refuses to let two worktrees check out the same branch at the same time. Try it and you'll get an error indicating the branch is already checked out in another worktree. Anyone tempted to work around this has missed the point of the feature, not found a clever shortcut: two processes writing commits against the same branch state at the same time is exactly the kind of collision worktrees exist to prevent.

A related misconception deserves clearing up directly. Opening two terminal tabs in the same directory does not give you two contexts. Run git switch in one tab and the files change under the other tab too, because they're the same directory. A worktree is a genuinely separate directory, and that distinction is the whole feature.

Core CLI commands for creating, managing, and cleaning up worktrees

Creating one is a single line:

git worktree add ../myapp-feature-auth feature/auth

That creates the sibling directory, checks out feature/auth into it, and writes the metadata Git needs into the .git/worktrees/ directory. Git names the worktree using the last segment of the path given to it, so naming the directory something recognizable matters more than it seems like it should.

git worktree list shows every active worktree for the repo: path, current HEAD SHA, and branch name, in a plain table. Add --porcelain when a script needs to parse the output instead of a human reading it.

Moving a worktree isn't just a filesystem operation. git worktree move fixes ../feature-2 updates the internal pointer tying the worktree back to the main repo, so Git still knows where to find it. The worktree keeps its original name (fixes, in this case) even after the physical move, which reads as confusing until you expect it going in. If something gets moved outside Git's awareness, by a file sync tool or a manual mv, git worktree repair {path} fixes the broken pointer.

Once a worktree's done its job, git worktree remove fixes deletes both the directory and its metadata in one step. For worktrees living on removable drives or network shares, git worktree lock stops Git's automatic pruning from cleaning them up just because they went temporarily unreachable. Git already prunes worktree metadata automatically for directories that have been missing for an extended period, so locking mainly matters for storage that goes offline for stretches at a time.

Every worktree is a complete, independent checkout. Run the test suite in one without touching any other, open each in its own editor window, push straight to remote from any of them. None of that requires a git checkout first. Just cd.

IDE and tooling support as of mid-2026

VS Code added native worktree support in its July 2025 release, tucked under Source Control → Repositories → Worktrees. From there, a developer can create a worktree, delete it, and open it either in the current window or a fresh one. It doesn't expose the entire CLI surface (no locking flags, no repair command visible in the UI), but it covers what comes up daily.

JetBrains shipped first-class worktree support in the 2026.1 release, which landed in March 2026. Earlier preview builds during that cycle needed a registry key to turn the feature on.

Both timelines point to the same fact: worktrees were fully usable through the CLI for years before either major IDE caught up. Waiting on IDE polish before adopting the feature cost teams real time for no good reason, and anyone comfortable typing git worktree add never needed to wait at all. For teams whose IDE support is still partial, or who need commands the UI doesn't expose, the CLI remains the interface that actually does everything.

How worktrees prevent the four failure modes of multi-agent repository work

Point several AI coding agents at the same working directory at once and the result resembles a distributed-systems concurrency bug, except worse, because the agents themselves have no way to notice when something has gone wrong.

The first failure mode is concurrent file overwrites. Two agents write to the same file at the same time, and one agent's changes vanish under the other's without warning, because Git's conflict detection operates on committed, divergent history. It has nothing to say about two processes editing the same file in memory inside a shared working directory.

The second is context contamination. Agent A refactors a service while Agent B is mid-task building something that consumes it. Agent B's working assumptions about that service are now wrong, silently, with no signal that anything changed until the two pieces of work collide later.

Third, shared infrastructure race conditions. Multiple agents each kicking off ./gradlew test, or all hitting the same test database at once, produce resource contention that slows every agent down together. Teams have documented building FIFO task queues specifically to manage this, a reasonable indication of how real the problem gets at scale.

Fourth, git lock contention. Concurrent git operations from multiple agents compete for .git/index.lock, and if one agent crashes mid-operation, it leaves that lock file behind. Every subsequent git command in that directory then fails until a person manually runs rm -f .git/index.lock.

Worktrees don't eliminate conflicts. They relocate them. Instead of surfacing silently mid-task, conflicts now show up at merge time, exactly where standard git tooling is built to catch them. What worktrees don't fix on their own is shared infrastructure below the filesystem: database connections, ports, anything agents might contend over that isn't a file. Teams still need to give each worktree its own database, whether that's a separate SQLite file, a separate Postgres instance, or a database-branching setup. Skipping that step is the most common reason teams conclude worktrees "didn't solve" a problem outside the scope of what worktrees were built to touch.

Structuring a worktree layout for parallel feature work

The layout that holds up in practice is sibling directories, all at the same level:

myapp/                    (main worktree, main branch)
myapp-feature-auth/
myapp-api-endpoints/
myapp-hotfix-login/

Each worktree lives on its own branch, and naming the directory after the branch, or close to it, saves real confusion later when git worktree list returns six entries and someone's trying to remember which is which.

Open each worktree in a separate editor window and each one keeps its own file index, its own search state, its own running processes: test watchers, dev servers, whatever's attached to that task. Switching between tasks becomes switching windows, or just cd-ing somewhere else, and nothing in the other worktree gets touched, uncommitted changes and all.

For AI agents specifically, this matters more than it does for a human developer, because the agent's entire working context is the filesystem in front of it. A worktree gives that agent a stable view of the codebase for the length of its task, uncontaminated by whatever another agent is doing three directories over.

Scale has a practical ceiling, though, and it's lower than the tooling makes it feel. Two to four parallel worktrees is a range where teams can generally operate without dedicated coordination tooling. Past that, the bottleneck moves from execution to review: someone still has to read every diff and decide the order to merge things in, and that cost climbs faster than the worktree count does. Large monorepos add another wrinkle, since each worktree needs its own full checkout, and running file watchers and build tools across several of those at once adds up in disk I/O fast.

Scripting and automating worktree creation for repeatable agent workflows

Manually running git worktree add, installing dependencies, and launching an agent by hand works fine for two parallel tasks. It stops working at four. Treating manual provisioning as a habit rather than a bottleneck is where most of these setups quietly fall apart.

incident.io's approach is a shell function, commonly named w, that takes a task name and handles the whole sequence: create the branch, add the worktree, spawn an isolated agent session against it. The team has reported that an $8 investment in Claude usage through this pattern produced an 18% build time improvement on API generation work that had sat deprioritized for months.

A fully scripted version looks like this:

git worktree add ../auth feature/authentication
git worktree add ../api feature/api-endpoints

followed by launching an agent session in the background against each directory. Teams running this pattern report throughput gains of 3x or more compared to sequential execution.

tmux comes up often as the orchestration layer: each headless agent session runs in its own named tmux pane, so a person can check in on any of them, or step in, without blocking a terminal or losing the others. On the CI side, running builds across worktrees in parallel rather than sequentially has taken total build time from 24 minutes down to 9, a reduction of roughly 63%.

None of this works if dependency installation stays a manual step. The setup script for each worktree needs to run npm install, activate whatever virtual environment the project uses, or start whatever container the task depends on, as part of provisioning the worktree, not as a thing a person remembers to do afterward.

Claude Code's native worktree integration and the isolation directive

Claude Code documentation recommends worktrees directly, describing the pattern as running multiple Claude sessions at once, each pointed at a different part of the project and focused on its own independent task.

The tool ships a --worktree flag that creates the isolated workspace and starts a session inside it in one step. Worktrees created this way land at <repo>/.claude/worktrees/<name>, branching off the default remote branch, with the new branch itself named worktree-<name>.

Sub-agents are defined as markdown files with YAML front matter, each one specifying its own tools, its own instructions, and its own scope of work. Adding an isolation: worktree directive to that front matter tells the orchestrator to provision a fresh worktree automatically for every parallel invocation of that sub-agent, no manual git worktree add required anywhere in the loop. The orchestrator handles delegation and, later, merge sequencing once each sub-agent's output has been checked.

incident.io runs this in practice: four or five parallel Claude Code agents at a time, each isolated in its own worktree, with no manual worktree management happening in between. Augment Code has documented scaling to 371 worktrees in a single repository, which is anecdotal and clearly well past what most teams need, but it shows how far the pattern scales when someone pushes it.

Running governed, auditable worktree-based agent sessions at scale

A worktree on someone's laptop is a good primitive. It is not, by itself, a governance model, and treating it like one is the mistake that gets teams burned once agents start touching production paths. There's no credential scoping built into it, no spend cap, no record of which agent made which change and why.

Each worktree-based agent session ought to be treated as a distinct unit of work, with credentials minted specifically for that session and revoked the moment the worktree closes. Sharing one set of credentials across every session through a global environment variable defeats the point of isolating the work in the first place.

Every tool call an agent makes, every diff it produces, every token it spends, should be logged and traced back to whatever triggered the session, whether a person, a scheduled job, or a CI event. Reconstructing that after the fact from git blame alone tells you what changed, not who asked for it or why, and that gap is where most incident postmortems stall out.

Spend needs a hard ceiling too, set at the session level, not just monitored after the money's gone. A session with no budget cap can run up cost in ways nobody notices until the bill arrives, so caps belong per worktree session, per developer, and per time window, enforced going in rather than flagged coming out.

Agent configuration itself belongs in the repo, as YAML or markdown, checked into version control like anything else a team ships. That means every change to how an agent behaves goes through the same pull request and review process as a code change, instead of living in some admin panel someone can edit without leaving a trace.

Worktrees are the right primitive for running agents concurrently. What turns that primitive into something safe to run across an entire engineering org, rather than one developer's machine, is a governed environment sitting on top of it.

Merging parallel work back without losing what each agent produced

Because every worktree lives on its own branch, nothing about merging changes just because an agent, rather than a person, did the work. Every conflict still surfaces at merge time, caught by ordinary git tooling, with no silent overwrites and no corrupted shared state to untangle afterward.

Order matters here, and deciding it upfront beats discovering it mid-merge. Branches should merge in the sequence their dependencies actually require, decided before the agents started, not in whatever order sessions happen to finish.

Each worktree's branch gets treated like any other: a pull request, automated checks, a human reviewer. The isolation that kept the agent's work clean during execution is what makes that same work independently reviewable afterward, since nothing else touched the branch while it was in progress.

Interdependent tasks need planning up front. If Agent A refactors something Agent B's branch depends on, Agent B will likely need a rebase once A merges, so decomposing the work to minimize that dependency before spawning agents saves far more time than untangling it later.

Cleanup is simple: git worktree remove once a branch has merged. Git's own pruning will eventually clear metadata for directories that vanish, after three months, but removing worktrees explicitly keeps the workspace legible in the meantime. And when an agent's output just isn't good enough to use, the fix is equally simple: remove the worktree. No revert needed, no stash to dig through, no trace left on the main branch.

The payoff shows up in the numbers already cited. The 3x throughput gain reported from parallel worktree workflows comes from tasks broken down carefully before any agent touched them, not from parallelism on its own. Parallel execution buys speed. Planning the split beforehand is what buys the coordination that makes the speed usable.