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 afraid of your personal workflow.
• Otherwise you begin poking at small issues when you wait. A typo in a docstring, a stray import, a README line that’s been bugging you. Then the Agent finishes, appears to be like on the diff, and begins speaking to itself: “I don’t remember adding this, let me clean 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 practice of thought at a time.

The repair just isn’t a greater immediate or a tighter scope. It’s a second working listing. That’s what Git worktrees provide you with, and this put up 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 practice of thought

A working listing holds precisely one practice 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 information on disk with out colliding. Prompts, context, and assessment don’t repair that. It’s a bodily constraint.

Branching doesn’t assist, both. Switching branches nonetheless mutates the one listing you have got open. If the Agent is midway by means of edits on characteristic/auth and also you git checkout fundamental to test a element, you both can’t swap (Git blocks you on the soiled tree) otherwise you drag the Agent’s in-progress adjustments onto the incorrect 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 contemporary distant. That’s precisely what a worktree is.

Worktrees in a single sentence

A worktree is a second working listing pointing on the similar 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 information for a department of your selecting. One command, one flag:

# from inside your fundamental 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 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 may park the brand new worktree outdoors the repo solely, 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 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 total 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 once you're completed (--force if it has uncommitted adjustments)
git worktree take away [--force] .worktrees/myrepo-auth

# clear up stale metadata after a guide 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 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 may see and edit the information for a particular department.

With out worktrees, you have got one window onto the repo and git checkout swaps what that window reveals. With worktrees, you have got a number of home windows open facet by facet, every locked to a unique department. You progress between them by shifting between terminals (or editor home windows, or tmux panes) with out the necessity to swap 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 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 reveals 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 reveals up in each different worktree immediately.

What worktrees are for, and what they aren’t

The axis break 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’t take a look at the identical department in two worktrees on the similar time. The second git worktree add will refuse, and it refuses for 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 to be like like this. You’ve an Agent iterating on feat/auth on a job that takes ten minutes to return again. You don’t want 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 assessment, apply options, 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 a giant 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. This can be 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 mum or dad department as they end. Worktrees then grow to be the enabling device, however the precise answer 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 fitting device. For 2 Brokers on the identical department, the repair is to decompose the department first.

Why this turned a giant deal when Brokers confirmed up

Zooming out for a second: this is the reason a decade-old Git characteristic is immediately in all places. 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 normally wish to work on three branches on the similar wall-clock minute.

However AI Brokers do.

After you have a device that may reliably execute a twenty-minute coding job within the background, the query “how many of these can I run at once?” turns into actual. Two? Three? 5? And the second you attempt to run two, you hit the working-directory downside, and worktrees are immediately the plain 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 yr have worktrees someplace within the stack.

However the greater 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, review what comes back”. You’re not in a coding bubble anymore. You’re in an orchestration bubble, juggling characteristic branches, checking which PR wants consideration, excited about how the items match collectively. Worktrees are what make that mode bodily potential, as a result of with out them you may’t even have three branches checked out on the similar 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 price 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 directly. Brokers modified the demand, and with it the developer’s position: from writing code to orchestrating parallel streams of labor.

The setup tax no person warns you about

Earlier than you hit price limits or assessment 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 contemporary listing with solely the information Git tracks. The whole lot talked about in your .gitignore is, by definition, not there. That sounds apparent once you learn it and painful once 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 anything you correctly stored out of model management. Your app received’t begin with out them.
• Ports. Two worktrees each operating npm run dev will combat over :3000, so operating 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 price opening a brand new worktree for a ten-minute repair, if it’s important to spend 5 minutes setting it up first?

In the event you reply truthfully, generally 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 put up about it.

Perception: The actual price of worktrees is every little thing gitignored that doesn’t come alongside: node_modules, .env information, 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 form of repetitive, mechanical, error-prone glue work that software program is sweet 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 means of a shell script?

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

However, it additionally runs out of highway quick. A script can not simply title a department for you once 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 mum or dad 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 contemporary spherical of hand-editing. The script is the fitting device for the mechanical half of the issue and the incorrect device for every little thing above it. Precisely the issues Brokers are good at.

So, by means of a Claude Code Talent then?

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

But, it’s nonetheless the incorrect reply. Mechanical file operations, hash-derived port offsets, and idempotent set up instructions are precisely the form 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 received’t uncover information in .gitignore by means 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 might be again to a script. You need this layer to be boring.

Combining each is finest

As you have got most likely guessed, the reply is to make use of every device 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 expertise on prime 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. One of the best reply is to mix each in a unified setup.

One script is definitely one script per repo

There’s a catch hiding in “just write a bash script”. A script that installs dependencies for a Subsequent.js frontend just isn’t 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 challenge, and re-writing them each time your stack drifts.

Studying a repo and determining its stack is precisely the form of factor the GenAI layer is sweet at. You possibly can write a second Talent 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 device you may 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 personal liking. If you wish to use it as-is, you may drop the Claude code expertise 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 information, derives a port offset, and runs the set up command.
• Drop a group of Claude Code expertise into .claude/expertise/*:
  • /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 an area git merge --no-ff right into a goal department, for folding sub-branches right into a mum or dad or batching small fixes.
  • /wt-close handles the tear-down of a worktree, and can be the place the optionally available 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 job

Finish to finish, adopting the toolkit in a repo and operating a parallel job appears to be like 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 job in its personal worktree
> /wt-open "add rate limiting to the auth endpoint"

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

# fold the completed sub-branch into its mum or dad 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 brief 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 is no such thing as a strategy 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 protected.

None of that is sacred. You possibly can 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 do not 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 price 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. This can be a sample price internalizing past worktrees: any device 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: Each time a device is nice in idea however the setup is simply too annoying to make use of constantly, 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 put up

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 reveals 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 fitting device. 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 directly. Brokers modified the demand, and with it the developer’s position: from writing code to orchestrating parallel streams of labor.
4. The actual price of worktrees is every little thing gitignored that doesn’t come alongside: node_modules, .env information, 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. One of the best reply is to mix each in a unified setup.
6. Each time a device is nice in idea however the setup is simply too annoying to make use of constantly, 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 direction of Information Science for early entry to new posts, or Medium for the total archive.

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