AI Brokers Want Their Personal Desk, and Git Worktrees Give Them One

Claude on a refactor. You recognize it’s going to take some time, and 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 fearful of your individual 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, appears 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 shouldn’t be a greater immediate or a tighter scope. It’s a second working listing. That’s what Git worktrees provide you with, and this submit covers what they’re, how they work, the setup price no person warns you about, and a small Claude Code toolkit I put collectively to make that price go away.

One listing, one prepare of thought

A working listing holds precisely one prepare of thought at a time. One Agent operating 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 recordsdata 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 could have open. If the Agent is midway by means of edits on function/auth and also you git checkout most important to verify a element, you both can’t change (Git blocks you on the soiled tree) otherwise you drag the Agent’s in-progress modifications onto the unsuitable department. Both approach, the isolation you wished is gone.

What you really need 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 unique department.

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

# from inside your most important repo
git worktree add .worktrees/myrepo-auth -b function/auth

That command creates a brand new folder at .worktrees/myrepo-auth inside your repo, checks out a model new department function/auth into it, and leaves your unique listing fully untouched. You now have two checkouts of the identical repo, every by itself department, sharing one underlying .git database. Your unique terminal, your editor, and your native dev server maintain operating on the department you had been already on, as if nothing occurred. Be 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 possibly can park the brand new worktree exterior the repo fully, like ../myrepo-auth.

You may also 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 title, not a department to take a look at. Claude parks the brand new listing underneath .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 function/auth

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

# checklist all worktrees
git worktree checklist

# take away a worktree whenever you're completed (--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 way in which you at all times have. There isn’t any worktree-specific Git dialect.

Branches and worktrees reside 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 possibly can see and edit the recordsdata for a selected department.

With out worktrees, you could have one window onto the repo and git checkout swaps what that window exhibits. With worktrees, you could have a number of home windows open aspect by aspect, every locked to a unique department. You progress between them by transferring between terminals (or editor home windows, or tmux panes) with out the necessity to change branches consistently.

Two necessary issues to pay attention to:

1. Eradicating a worktree doesn’t take away the department. git worktree take away ../myrepo-auth deletes the bodily listing, however function/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 reside in your repo’s historical past. Worktrees reside 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 take a look at the identical department in two worktrees on the identical time. The second git worktree add will refuse, and it refuses for an excellent 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 appears like this. You’ve an Agent iterating on feat/auth on a job that takes ten minutes to return again. You do not need to sit down and wait, and you don’t want to change 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 recommendations, 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 might be 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 mother or father department as they end. Worktrees then turn out to be the enabling software, however the precise resolution right here is job 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 best 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 function is all of a sudden all over the place. Worktrees have existed in Git since 2015. For many of that decade they had been a distinct segment power-user function that not many wanted nor knew about, as a result of people don’t often wish 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 job 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 drawback, and worktrees are all of a sudden the apparent reply. For this 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 operating 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 function branches, checking which PR wants consideration, serious about how the items match collectively. Worktrees are what make that mode bodily potential, as a result of with out them you possibly can’t even have three branches checked out on the identical time.

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

Perception: Worktrees had been a distinct segment function 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 fee 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 recordsdata Git tracks. All the things talked about in your .gitignore is, by definition, not there. That sounds apparent whenever you learn it and painful whenever you reside it.

Issues that aren’t in a brand new worktree:

• node_modules/, .venv/, or no matter your bundle 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 properly stored out of model management. Your app gained’t begin with out them.
• Ports. Two worktrees each operating npm run dev will struggle over :3000, so operating them aspect by aspect 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 truthfully, typically the reply is “no”. So that you skip the worktree, share the listing together with your Agent once more, the Agent undoes your work, and also you write a weblog submit about it.

Perception: The actual price of worktrees is the whole lot gitignored that doesn’t come alongside: node_modules, .env recordsdata, construct caches, virtualenvs. Finances 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 precisely the sort of repetitive, mechanical, error-prone glue work that software program is nice at. The apparent transfer is to automate it: wrap git worktree add, copy the .env recordsdata, run the set up command, and floor a single command that does all three. However how?

Via a shell script?

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

However, it additionally runs out of street quick. A script can not simply title a department for you whenever you describe a change in a single sentence. It can not resolve whether or not a small repair ought to undergo a PR or fold regionally right into a mother or father department. It can not learn your repo, discover you might be 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 best software for the mechanical half of the issue and the unsuitable software for the whole lot above it. Precisely the issues Brokers are good at.

So, by means of a Claude Code Ability then?

If a script is simply too inflexible, the other intuition is handy the entire thing to an Agent. Write a talent, let’s say /wt-open (spoiler: we’ll really construct this talent later, as soon as we’ve seen why it isn’t sufficient by itself), and let Claude Code determine the department title, the set up command, the port config, and the file copying. That solves the flexibleness drawback.

But, it’s nonetheless the unsuitable reply. Mechanical file operations, hash-derived port offsets, and idempotent set up instructions are precisely the sort of deterministic work an Agent is dangerous at. It’s slower, it may well 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 high: Claude Code abilities gained’t uncover recordsdata in .gitignore by means of search or glob. .worktreeinclude solves this for a static checklist of recordsdata you keep by hand, however the second you need conditional logic, monorepo-aware paths, or something past a flat copy, you might be again to a script. You need this layer to be boring.

Combining each is greatest

As you could have 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 primary 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 operating the set up command. Plain shell, boring on function.
2. A set of Claude Code abilities on high for what the Agent is definitely good at. Naming a department from a one-sentence description, selecting 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 very best 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 shouldn’t 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 precisely the sort of factor the GenAI layer is nice at. You possibly can write a second Ability whose solely job is to learn bundle.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 possibly can 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 isn’t a product, however a place to begin so that you can fork and bend to your individual liking. If you wish to use it as-is, you possibly can drop the Claude code abilities and setup script into any git repo by means 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 recordsdata, derives a port offset, and runs the set up command.
• Drop a group of Claude Code abilities into .claude/abilities/*:
  • /wt-open creates or reopens a worktree from a department title or a one-sentence job 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 mother or father or batching small fixes.
  • /wt-close handles the tear-down of a worktree, and can be the place the non-compulsory push lives (--push).
  • /wt-list a richer git worktree checklist with clear/soiled, forward/behind, and rancid 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 job

Finish to finish, adopting the toolkit in a repo and operating a parallel job appears like this:

# one-time: drop the script and abilities 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 on your stack
> /wt-adopt

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

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

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

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

Underneath the hood

A bit extra on the components that matter. The bash script creates the worktree underneath .claude/worktrees/- (the brief hash guards in opposition to 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 on 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 aspect impact.

The port block and the set up block in that script ship commented out, as a result of there is no such thing as a technique 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 on your personal migrations, seeds, and construct warmups. That block is rarely overwritten, so re-running /wt-adopt after a stack change is at all times secure.

None of that is sacred. You possibly can at all times iterate on each wt-setup.sh or the talents regionally if wanted. Additionally, the repo is small, MIT-licensed, and intentionally easy. Fork it in order for you, rename the talents, rip out the bits you do not want, swap the set up part for no matter matches your precise coding workflow greatest. The purpose is the strategy, 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, they usually do it with out cloning repos, preventing remotes, or inventing a brand new workflow.

The one actual price is setup overhead, and setup overhead is the precise drawback 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 idea however too annoying to arrange in observe 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 idea however the setup is simply too annoying to make use of persistently, that friction is a talent ready to be written. Use the Agent you might be already operating to construct the tooling that onboards the following one.

Key insights from this submit

1. Branches reside in your repo’s historical past. Worktrees reside 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 best software. For 2 Brokers on the identical department, the repair is to decompose the department first.
3. Worktrees had been a distinct segment function 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 actual price of worktrees is the whole lot gitignored that doesn’t come alongside: node_modules, .env recordsdata, construct caches, virtualenvs. Finances 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 very best reply is to mix each in a unified setup.
6. Every time a software is nice in idea however the setup is simply too annoying to make use of persistently, that friction is a talent ready to be written. Use the Agent you might be already operating to construct the tooling that onboards the following one.

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

Comply with me on LinkedIn for bite-sized AI insights, In the direction of Knowledge 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.