AI Agents Need Their Own Desk, and Git Worktrees Give Them One

Claude on a refactor. it’s going to take some time, and you already know precisely what comes subsequent.

• Both you sit there and watch the stream scroll, doomscroll a bit whereas ready, half afraid that touching something will corrupt the run. Twenty minutes of your day, gone, since you’re frightened of your personal workflow.
• Otherwise you begin poking at small issues whilst you wait. A typo in a docstring, a stray import, a README line that’s been bugging you. Then the Agent finishes, seems on the diff, and begins speaking to itself: “I don’t keep in mind including this, let me clear it up”. You watch it calmly revert your work as a result of it doesn’t match the scope it was given.

Each choices are the identical bug with completely different signs. You and the Agent are sharing one working listing, and a working listing can solely maintain one prepare of thought at a time.

The repair will not be a greater immediate or a tighter scope. It’s a second working listing. That’s what Git worktrees offer you, and this put up covers what they’re, how they work, the setup value no person warns you about, and a small Claude Code toolkit I put collectively to make that value go away.

One listing, one prepare of thought

A working listing holds precisely one prepare of thought at a time. One Agent working in your repo is simple. Two Brokers, or one Agent plus you, is the place it breaks, as a result of two entities can not edit the identical information on disk with out colliding. Prompts, context, and evaluate don’t repair that. It’s a bodily constraint.

Branching doesn’t assist, both. Switching branches nonetheless mutates the one listing you’ve got open. If the Agent is midway by way of edits on characteristic/auth and also you git checkout principal to examine a element, you both can’t swap (Git blocks you on the soiled tree) otherwise you drag the Agent’s in-progress modifications onto the flawed department. Both means, the isolation you needed is gone.

What you really want is a second copy of the repo that the Agent can personal, ideally with out the overhead of a full git clone and a recent distant. That’s precisely what a worktree is.

Worktrees in a single sentence

A worktree is a second working listing pointing on the identical Git repository, locked to a distinct department.

In plain phrases: you ask Git to create a brand new folder someplace in your disk, and it fills that folder along with your repo’s information for a department of your selecting. One command, one flag:

# from inside your principal repo
git worktree add .worktrees/myrepo-auth -b characteristic/auth

That command creates a brand new folder at .worktrees/myrepo-auth inside your repo, checks out a model new department characteristic/auth into it, and leaves your authentic listing utterly untouched. You now have two checkouts of the identical repo, every by itself department, sharing one underlying .git database. Your authentic terminal, your editor, and your native dev server maintain working on the department you had been already on, as if nothing occurred. Make certain .worktrees/ is in your .gitignore so the brand new folder by no means finally ends up tracked by the very repo it lives inside. Alternatively, you’ll be able to park the brand new worktree exterior the repo totally, like ../myrepo-auth.

It’s also possible to let Claude Code create worktrees for you straight. It has a local --worktree flag (-w) that creates the worktree and launches the session in a single step:

claude --worktree feature-auth

The argument is a worktree identify, not a department to take a look at. Claude parks the brand new listing beneath .claude/worktrees/feature-auth and branches off your default distant department into worktree-feature-auth. Identical rule as earlier than: gitignore .claude/worktrees/ so it by no means will get dedicated.

Worktrees cheat sheet

5 instructions cowl the day-to-day worktree lifecycle. Bookmark this block and you’ve got the complete floor:

# create a worktree on a brand new department
git worktree add .worktrees/myrepo-auth -b characteristic/auth

# create a worktree on an current department
git worktree add .worktrees/myrepo-hotfix hotfix/login

# record all worktrees
git worktree record

# take away a worktree while you're performed (--force if it has uncommitted modifications)
git worktree take away [--force] .worktrees/myrepo-auth

# clear up stale metadata after a handbook rm -rf
git worktree prune

Inside a worktree you commit, push, pull, rebase, and open PRs precisely the best way you at all times have. There is no such thing as a worktree-specific Git dialect.

Branches and worktrees stay on completely different axes

The important thing psychological mannequin: a department is a named line of commits in your repo’s historical past, nothing extra. It has no bodily location. A worktree is a listing in your filesystem. It’s a spot the place you’ll be able to see and edit the information for a particular department.

With out worktrees, you’ve got one window onto the repo and git checkout swaps what that window exhibits. With worktrees, you’ve got a number of home windows open facet by facet, every locked to a distinct department. You progress between them by shifting between terminals (or editor home windows, or tmux panes) with out the necessity to swap branches continuously.

Two vital issues to concentrate on:

1. Eradicating a worktree doesn’t take away the department. git worktree take away ../myrepo-auth deletes the bodily listing, however characteristic/auth and all its commits are nonetheless within the repo. The listing was only a viewing window. Closing it doesn’t contact the historical past.
2. Commits are seen throughout worktrees immediately. All of your worktrees share one .git database, so a commit made in a single exhibits up in git log from one other with no push, pull, or sync.

Perception: Branches stay in your repo’s historical past. Worktrees stay in your filesystem. They exist on completely different axes, which is why eradicating a worktree doesn’t contact the department, and why a commit made in a single worktree exhibits up in each different worktree immediately.

What worktrees are for, and what they aren’t

The axis cut up has a sensible consequence that journeys individuals up the primary time they attempt to parallelize brokers: worktrees parallelize branches, not brokers. Git enforces this straight. You can not try the identical department in two worktrees on the identical time. The second git worktree add will refuse, and it refuses for a very good motive, as a result of two directories mutating the identical department pointer is chaos.

What they’re for: parallel work on completely different branches. The canonical state of affairs seems like this. You could have an Agent iterating on feat/auth on a process that takes ten minutes to come back again. You do not need to take a seat and wait, and you don’t want to modify branches and lose your home. So that you open a worktree for feat/billing and begin the following piece of labor there. When the feat/auth Agent finishes, you swap terminals, not branches. One tab is already sitting within the feat/auth worktree with its personal dev server, its personal .env, its personal node_modules, precisely as you left it. You evaluate, apply ideas, push, and return to the opposite tab. Neither department ever needed to be stashed, checked out, or re-bootstrapped.

What they aren’t for: a number of Brokers on the identical department. Suppose you’re doing an enormous frontend overhaul on feat/frontend-redo and also you need three Brokers chipping away at it in parallel. The intuition is “three worktrees on feat/frontend-redo“. Git will refuse, and even when it didn’t, the Brokers would stomp one another’s commits within the shared historical past. It is a branch-level constraint, and the filesystem has nothing to do with it. The repair is upstream: decompose the overhaul into sub-branches (feat/frontend-redo-nav, feat/frontend-redo-table, feat/frontend-redo-auth) off feat/frontend-redo, run every in its personal worktree, and merge them again into the native father or mother department as they end. Worktrees then turn out to be the enabling software, however the precise answer right here is process decomposition.

Perception: Worktrees parallelize branches, not Brokers. Git refuses to take a look at the identical department in two worktrees on function, and that rule is the form of the expertise. For parallel work on completely different branches, worktrees are the correct software. For 2 Brokers on the identical department, the repair is to decompose the department first.

Why this turned an enormous deal when Brokers confirmed up

Zooming out for a second: for this reason a decade-old Git characteristic is out of the blue all over the place. Worktrees have existed in Git since 2015. For many of that decade they had been a distinct segment power-user characteristic that not many wanted nor knew about, as a result of people don’t often need to work on three branches on the identical wall-clock minute.

However AI Brokers do.

After you have a software that may reliably execute a twenty-minute coding process within the background, the query “what number of of those can I run without delay?” turns into actual. Two? Three? 5? And the second you attempt to run two, you hit the working-directory downside, and worktrees are out of the blue the apparent reply. This is the reason claude --worktree exists as a first-class flag, and why most severe write-ups on parallel agentic coding within the final 12 months have worktrees someplace within the stack.

However the larger shift is what occurs to you. When three Brokers are working in parallel, your job stops being “write the code” and begins being “decompose the work, assign it, evaluate what comes again”. You’re not in a coding bubble anymore. You’re in an orchestration bubble, juggling characteristic branches, checking which PR wants consideration, enthusiastic about how the items match collectively. Worktrees are what make that mode bodily doable, as a result of with out them you’ll be able to’t even have three branches checked out on the identical time.

A sensible word on the ceiling: three to 5 concurrent Brokers in my expertise, earlier than issues get unwieldy. The bottleneck is never Git. It’s charge limits from the mannequin supplier, and the cognitive overhead of reviewing 5 PRs in flight.

Perception: Worktrees had been a distinct segment characteristic for a decade as a result of people hardly ever want three branches open without delay. Brokers modified the demand, and with it the developer’s function: from writing code to orchestrating parallel streams of labor.

The setup tax no person warns you about

Earlier than you hit charge limits or evaluate overload, you’ll hit a extra mundane ceiling: each new worktree must be bootstrapped from scratch. Right here’s the half the enthusiastic weblog posts skip. A worktree is a recent listing with solely the information Git tracks. Every part talked about in your .gitignore is, by definition, not there. That sounds apparent while you learn it and painful while you stay it.

Issues that aren’t in a brand new worktree:

• node_modules/, .venv/, or no matter your package deal supervisor builds. You get to reinstall.
• Construct artifacts like dist/, .subsequent/, goal/, or __pycache__/. First construct is at all times chilly.
• .env and the rest you correctly saved out of model management. Your app gained’t begin with out them.
• Ports. Two worktrees each working npm run dev will battle over :3000, so working them facet by facet means giving each its personal port vary.

For a small Python repo that is thirty seconds of annoyance. For a contemporary monorepo with a 400 MB node_modules tree, a Subsequent.js construct cache, and a .env with twelve secrets and techniques in it, that is 5 to 10 minutes of setup for each worktree you spin up. This raises a good query: is it nonetheless value opening a brand new worktree for a ten-minute repair, if you must spend 5 minutes setting it up first?

In the event you reply actually, generally the reply is “no”. So that you skip the worktree, share the listing along with your Agent once more, the Agent undoes your work, and also you write a weblog put up about it.

Perception: The true value of worktrees is every thing gitignored that doesn’t come alongside: node_modules, .env information, construct caches, virtualenvs. Funds a number of minutes of setup per worktree on a contemporary monorepo, or automate it away.

Decreasing the tax by letting the Agent pay it

The setup tax is strictly the type of repetitive, mechanical, error-prone glue work that software program is nice at. The plain transfer is to automate it: wrap git worktree add, copy the .env information, run the set up command, and floor a single command that does all three. However how?

By a shell script?

The only reply is a bash script. Wrap git worktree add, copy the .env information, run npm set up or uv sync, performed. It really works, and for a single repo with a single stack it really works effectively.

However, it additionally runs out of street quick. A script can not simply identify a department for you while you describe a change in a single sentence. It can not determine whether or not a small repair ought to undergo a PR or fold regionally right into a father or mother department. It can not learn your repo, discover you’re on Subsequent.js plus FastAPI, and configure itself accordingly. Each repo you drop it into is a recent spherical of hand-editing. The script is the correct software for the mechanical half of the issue and the flawed software for every thing above it. Precisely the issues Brokers are good at.

So, by way of a Claude Code Ability then?

If a script is just too inflexible, the other intuition is at hand the entire thing to an Agent. Write a talent, let’s say /wt-open (spoiler: we’ll truly construct this talent later, as soon as we’ve seen why it’s not sufficient by itself), and let Claude Code work out the department identify, the set up command, the port config, and the file copying. That solves the flexibleness downside.

But, it’s nonetheless the flawed reply. Mechanical file operations, hash-derived port offsets, and idempotent set up instructions are precisely the type of deterministic work an Agent is unhealthy at. It’s slower, it could drift between runs, and also you’ll spend extra time arguing with the Agent or fixing the setup than doing it your self. There’s a smaller, sensible wrinkle on prime: Claude Code expertise gained’t uncover information in .gitignore by way of search or glob. .worktreeinclude solves this for a static record of information you keep by hand, however the second you need conditional logic, monorepo-aware paths, or something past a flat copy, you’re again to a script. You need this layer to be boring.

Combining each is finest

As you’ve got most likely guessed, the reply is to make use of every software for what it’s good at:

1. A bash script for what the Agent can not see, and shouldn’t be doing anyway. Creating the worktree, strolling the principle repo, copying each .env* file into the brand new listing (preserving subdirectory construction for monorepos), deriving deterministic port offsets so dev servers in numerous worktrees don’t collide, and working the set up command. Plain shell, boring on function.
2. A set of Claude Code expertise on prime for what the Agent is definitely good at. Naming a department from a one-sentence description, choosing a merge technique, writing a PR description, deciding whether or not to delete a department after cleanup, and studying the repo’s stack to configure the bash script within the first place.

Perception: A shell script is versatile sufficient to deal with mechanical setup however too inflexible for something above it. A talent is versatile sufficient to deal with the reasoning however shouldn’t be doing deterministic file work within the first place. The perfect reply is to mix each in a unified setup.

One script is definitely one script per repo

There’s a catch hiding in “simply write a bash script”. A script that installs dependencies for a Subsequent.js frontend will not be the identical script that installs for a Rust workspace or a Python monorepo. The set up command differs. The default port numbers differ. Whether or not there’s a make setup goal differs. The file-copy and port-derivation logic is generic, however the set up and port blocks are repo-specific. So you find yourself hand-writing these two blocks as soon as per venture, and re-writing them at any time when your stack drifts.

Studying a repo and determining its stack is strictly the type of factor the GenAI layer is nice at. You’ll be able to write a second Ability whose solely job is to learn package deal.json, pyproject.toml, Dockerfile, docker-compose.yml, Makefile, and .env.instance, work out the set up command and the ports, and fill within the empty slots in a predefined “setup” bash script. Let the Agent audit your repo’s worktree-readiness, and repair the open gaps.

A concrete worktree administration software you’ll be able to borrow

To avoid wasting you the hours of wiring the 2 layers collectively your self, I (learn: Claude) wrote a small worktree toolkit and put it on GitHub as ThinkVelta/claude-worktree-tools. It’s not a product, however a place to begin so that you can fork and bend to your personal liking. If you wish to use it as-is, you’ll be able to drop the Claude code expertise and setup script into any git repo by way of a single command:

npx @thinkvelta/claude-worktree-tools

What the installer drops into your repo

This script will do the next:

• Create scripts/wt-setup.sh, the bash bootstrapping layer that creates the worktree, copies .env information, derives a port offset, and runs the set up command.
• Drop a set of Claude Code expertise into .claude/expertise/*:
  • /wt-open creates or reopens a worktree from a department identify or a one-sentence process description, and runs wt-setup.sh for you.
  • /wt-merge does a neighborhood git merge --no-ff right into a goal department, for folding sub-branches right into a father or mother or batching small fixes.
  • /wt-close handles the tear-down of a worktree, and can also be the place the elective push lives (--push).
  • /wt-list a richer git worktree record with clear/soiled, forward/behind, and off warnings.
  • /wt-cleanup batch housekeeping for stale worktrees and native branches whose distant was deleted after a PR merge.
  • /wt-adopt the personalization talent from the earlier part, which reads your stack and fills within the repo-specific sections of wt-setup.sh.
  • /wt-help the in-repo FAQ for VSCode integration, gitignore questions, and the port-offset mechanics.

From set up to first parallel process

Finish to finish, adopting the toolkit in a repo and working a parallel process seems like this:

# one-time: drop the script and expertise into the repo
npx @thinkvelta/claude-worktree-tools

# from right here, you proceed in a Claude session
claude

# as soon as per repo Claude ought to fill within the set up and port blocks in your stack
> /wt-adopt

# begin a brand new parallel process in its personal worktree
> /wt-open "add charge limiting to the auth endpoint"

# ... Agent works, dev server runs on an auto-assigned port offset ...

# fold the completed sub-branch into its father or mother regionally
> /wt-merge feat/auth

# tear down the worktree and push the department in a single go
> /wt-close --push

Beneath the hood

A bit extra on the components that matter. The bash script creates the worktree beneath .claude/worktrees/- (the quick hash guards towards branches that differ solely in slash placement, like feat/a-b vs feat/a/b), copies each .env* file throughout, derives a port offset (0–99) from a hash of the worktree path so every worktree runs by itself ports and by no means fights with one other worktree over the identical port, and runs the set up command in your stack. As a result of the offset is derived from the trail, the identical department at all times will get the identical ports, which suggests bookmarkable URLs as a free facet impact.

The port block and the set up block in that script ship commented out, as a result of there isn’t any approach to write them generically. Filling them in is what /wt-adopt is for. It additionally preserves a devoted USER-DEFINED EXTRA SETUP block on the backside of the script in your personal migrations, seeds, and construct warmups. That block isn’t overwritten, so re-running /wt-adopt after a stack change is at all times secure.

None of that is sacred. You’ll be able to at all times iterate on each wt-setup.sh or the abilities regionally if wanted. Additionally, the repo is small, MIT-licensed, and intentionally easy. Fork it if you’d like, rename the abilities, rip out the bits you don’t want, swap the set up part for no matter matches your precise coding workflow finest. The purpose is the method, not the code itself.

Takeaway

You and your AI Agent can not share a desk. You’ve felt this each time you’ve sat frozen watching a run end, or watched an Agent calmly undo a change you made whereas it was pondering. Worktrees give the Agent its personal desk, and so they do it with out cloning repos, combating remotes, or inventing a brand new workflow.

The one actual value is setup overhead, and setup overhead is the precise downside your Agent was constructed to unravel. Give it a worktree. Then give it the talent that units up the following one. It is a sample value internalizing past worktrees: any software that’s nice in concept however too annoying to arrange in follow is a talent ready to be written. Brokers are right here to take away the friction of getting began with Brokers (how meta).

Perception: Every time a software is nice in concept however the setup is just too annoying to make use of persistently, that friction is a talent ready to be written. Use the Agent you’re already working to construct the tooling that onboards the following one.

Key insights from this put up

1. Branches stay in your repo’s historical past. Worktrees stay in your filesystem. They exist on completely different axes, which is why eradicating a worktree doesn’t contact the department, and why a commit made in a single worktree exhibits up in each different worktree immediately.
2. Worktrees parallelize branches, not Brokers. Git refuses to take a look at the identical department in two worktrees on function, and that rule is the form of the expertise. For parallel work on completely different branches, worktrees are the correct software. For 2 Brokers on the identical department, the repair is to decompose the department first.
3. Worktrees had been a distinct segment characteristic for a decade as a result of people hardly ever want three branches open without delay. Brokers modified the demand, and with it the developer’s function: from writing code to orchestrating parallel streams of labor.
4. The true value of worktrees is every thing gitignored that doesn’t come alongside: node_modules, .env information, construct caches, virtualenvs. Funds a number of minutes of setup per worktree on a contemporary monorepo, or automate it away.
5. A shell script is versatile sufficient to deal with mechanical setup however too inflexible for something above it. A talent is versatile sufficient to deal with the reasoning however shouldn’t be doing deterministic file work within the first place. The perfect reply is to mix each in a unified setup.
6. Every time a software is nice in concept however the setup is just too annoying to make use of persistently, that friction is a talent ready to be written. Use the Agent you’re already working to construct the tooling that onboards the following one.

Last perception: Your AI Agent can’t share a desk with you. Give it its personal, and let it arrange the following ones.

Observe me on LinkedIn for bite-sized AI insights, Towards Data Science for early entry to new posts, or Medium for the complete archive.

All photographs on this article had been generated on my own utilizing GPT-4o picture era.