Big Idea

The argument in one line.

Git worktrees solve the parallel-agent file-collision problem by giving each agent a fully isolated checkout of the same repository — so two agents can build features simultaneously without ever touching the same files.

Who This Is For

Read if. Skip if.

READ IF YOU ARE…

You already use Claude Code or Codex daily and feel like you waste time waiting for an agent to finish before starting the next task.
You have tried opening two Claude sessions in the same directory and hit mysterious conflicts or broken state.
You want to run architecture explorations without committing to one approach — seeing two implementations side by side before deciding.
You work on projects with clearly separable features that do not share source files.

SKIP IF…

You are new to git branching — this tutorial assumes comfort with git checkout, commit, and push.
Your tasks routinely touch the same files, making true parallelism impractical regardless of worktrees.

TL;DR

The full version, fast.

When two AI agents share a working directory they corrupt each other's in-progress changes. Git worktrees fix this by decoupling the object store (shared history, branches, remotes) from the working tree (the files on disk), letting you check out one branch per directory. Each agent gets its own directory, its own branch, and zero awareness of what the others are doing. The video walks through the CLI to create worktrees, a live split-screen demo of two Codex sessions building unrelated features in parallel, and three advanced patterns: scoped CLAUDE.md files per worktree, agent-vs-agent architecture comparison (same task, two agents, pick the winner), and TMux named sessions for persistent agent checkpoints.

Free for members

Chat with this breakdown — free.

Sign in and you get 23 free chat messages on us — ask for the hook, quote a framework, find the exact transcript moment, generate a markdown action plan. Bring your own key when you want unlimited.

Create a free account →

Chapters

Where the time goes.

00:00 – 00:55

01 · The problem

Idle time between agent tasks and the chaos that erupts when two agents share a working directory

00:56 – 02:17

02 · What a worktree is

Object store vs. working tree; the satellite analogy; one repo, multiple independent file checkouts

02:17 – 07:13

03 · CLI walkthrough

git worktree list, git branch, git worktree add with -b and origin/staging; naming conventions

07:13 – 12:37

04 · Live parallel demo

Two Codex sessions running simultaneously — DeFi Llama backend in dashboard-creation, select-all UI in hubspot-access

12:37 – 14:48

05 · Commit, push, PR

Reviewing git status on each side, committing, opening a PR to staging on GitHub; merge conflict warning

15:01 – 16:23

06 · Scoped MD files

Root CLAUDE.md or agents.md propagates to all worktrees; add a worktree-level MD for feature-specific context

16:23 – 17:07

07 · Agent vs. agent comparison

Same task, two worktrees, pick the better implementation — same wall-clock time, half the opportunity cost

17:07 – 19:15

08 · TMux persistent sessions

tmux new-session per worktree, named after the feature; sessions survive terminal close; tmux ls as a dashboard

19:15 – 19:56

09 · When to use worktrees

Use for independent parallel tasks or architecture comparisons; single session for whole-codebase or exploratory work

Atomic Insights

Lines worth screenshotting.

Two AI agents running in the same directory corrupt each other silently — they write to the same files and have no idea why the code keeps changing under them.
Git worktrees decouple the object store from the working tree, letting one repo support multiple isolated checkouts on different branches simultaneously.
The main repo is the source of truth; each worktree is a satellite — same history and remotes, completely separate files on disk.
The command is three words: git worktree add ../project-feature -b branch-name origin/staging.
Naming every worktree directory with the project prefix means a single ls command shows your entire parallel work queue in one place.
Agent-vs-agent comparison is more valuable than parallelism: give two agents the identical task, review both outputs, discard the loser — same wall clock time, half the opportunity cost.
A root CLAUDE.md or agents.md propagates context to every worktree automatically; a worktree-level MD file adds scoped context for a specific feature without polluting the others.
TMux named sessions let agent instances survive terminal closures — tmux ls gives you a live dashboard of every agent currently running across all worktrees.
Worktrees are wrong for tasks that span the whole codebase or require exploratory roaming; they shine when features are clearly separable at the file level.
Merge conflicts are still possible if two agents eventually modify the same file in different branches — worktrees prevent runtime collision, not git-level conflicts.

Takeaway

One git command unlocks parallel AI development.

WHAT TO LEARN

The collision between parallel AI sessions is a file-system problem, not an AI problem — and git worktrees fix it at the source by giving each agent its own isolated checkout.

01The problem

Two agents in the same directory silently corrupt each other because they both read and write the same files with no coordination — this is structural, not a bug in the agents.

02What a worktree is

A git worktree is a second (or third, or fourth) checked-out branch in a separate directory, sharing history and remotes but with completely independent files on disk.

03CLI walkthrough

Creating one takes a single command: git worktree add ../project-feature -b branch-name origin/main.
Naming every worktree directory with the project prefix lets a single ls command show your entire parallel work queue grouped together.

04Live parallel demo

Separate directories are what enable true parallelism — each agent updates only the files in its own worktree, so back-end and front-end work can proceed simultaneously.

05Commit, push, PR

Each worktree commits to its own branch independently; merge conflicts can still arise at PR time if branches touched the same file — worktrees prevent runtime collision, not git-level conflicts.

06Scoped MD files

A root CLAUDE.md or agents.md propagates its context to every worktree automatically — you only need to maintain one shared context file for the project.
Adding a worktree-level context file scopes extra instructions to one feature without polluting the global context.

07Agent vs. agent comparison

The highest-leverage use of worktrees is not parallelism but comparison: give two agents the same task, review both outputs, and discard the loser — the total time cost is identical to a single run.

08TMux persistent sessions

TMux named sessions make agent instances persistent: a session survives a terminal close, and tmux ls gives a live status board of every agent currently working across all worktrees.

09When to use worktrees

Worktrees are wrong for tasks that require one agent to roam the entire codebase — the isolation that protects parallel sessions also limits an exploratory agent to one branch.

Glossary

Terms worth knowing.

Worktree: A Git feature that lets one repository have multiple simultaneously checked-out branches in separate directories on disk. Each worktree is fully independent at the file level but shares the same commit history and remote configuration.
Object store: The .git directory containing all commits, branches, tags, and history for a repository. Worktrees share one object store while maintaining separate working directories.
Working tree: The set of files you actually see on disk when you open a project — as opposed to the compressed commit history stored in the object store. Normally one repo has one working tree; worktrees add more.
TMux: A terminal multiplexer that lets you run multiple shell sessions inside a single terminal window, detach from them, and reattach later without losing state. Used here to give each agent worktree a persistent named session.
agents.md / CLAUDE.md: A markdown file at the root of a project that provides AI coding assistants with standing context about the codebase, conventions, and commands. Both propagate to every worktree automatically.

Quotables

Lines you could clip.

00:29

“When two agents are in the same working directory, they read and write to the same files. So as each agent is working, the code is changing right in front of them, and they have no idea why or how. And all of a sudden, everything just breaks.”

Crisp diagnosis of a pain point every AI coder has hit→ TikTok hook↗ Tweet quote

01:59

“Your main repo is the source of truth, and a work tree is like a satellite.”

Sticky analogy, standalone without any setup→ IG reel cold open↗ Tweet quote

16:23

“In my opinion, the most useful work tree pattern is actually not parallelism, but comparison with multiple agents.”

Counterintuitive claim that reframes the whole video→ newsletter pull-quote↗ Tweet quote

16:59

“The cost of exploring two approaches is not double the time in this case. It's the same time with half the opportunity cost.”

Business framing for a technical technique→ newsletter pull-quote↗ Tweet quote

The Script

Word for word.

Read-along

Don't just watch it. Burn it in.

See every word as it's spoken — crank it to 2× and still catch all of it. The same dual-channel trick behind Amazon's Kindle + Audible.

metaphoranalogy

In this video, I'm going to cover one of my favorite ways to optimize my day to day coding workflow, and that's by using Git Worktrees with Claude. So, typically, if you're working with Claude, you'll open a session, give it a task, review it, and continue to iterate until that task is completed. But what are you doing when your LLM is actively thinking and working?

Sometimes it can feel like you're just twiddling your thumbs waiting for something else to do. But if you look at your backlog, chances are there's several tasks that aren't actually dependent on one another. So there's no reason that one task has to finish before you start the next.

But if you open two terminals and you run Cloud Code in both, you do get to work on both tasks, but you'll quickly realize that just makes a mess. When two agents are in the same working directory, they read and write to the same files. So as each agent is working, the code is changing right in front of them, and they have no idea why or how.

And all of a sudden, everything just breaks. So what's actually the solution here? Well, it's not a change in Cloud Code or any other LLM that you're working with, but it's a change in how you're using GitHub.

A Git repository has two things, the object store, which has all your commits, all your history, all your branches, and then the working tree, which are the files that you actually see on disk when you open your editor, meaning the files that are on your machine. Normally, are coupled.

One repo, one working tree. You check out a branch, your files change to match that branch, and you can only be on one branch at a time in one directory on your computer. But Git work trees are how you decouple them.

So you still have one object object store. Store. So you have one repo, one git directory, one history, but now you have multiple working trees.

And each working tree is a separate directory on your computer checked out to a different branch. So it's completely independent at the file level, and changes in one working tree do not affect any other. You can think of it this way.

Your main repo is the source of truth, and a work tree is like a satellite. It's a separate checkout of the same repo on a different branch in a different folder. So they share the same history and they share the same remotes, but they don't share files on your computer storage.

So as each agent builds out its own feature that it's tasked with, it's not affecting any other. Now let's walk through how to actually do this in practice. So first, we're gonna use the git CLI to create and manage work trees.

So navigate into a directory that has an active git repo. So I'm currently in my AI agent project, and we're just gonna type in git work tree list.

And this is gonna list out all of the work trees that you have associated with this repository. Now you can see I already have some work trees connected here. This is because it's my current project at work.

So by the end of this video, you'll actually get a sneak peek into what my screen looks like when I'm deep into building a real project. But if you're following along, you won't have any work trees here. It'll just return main.

So let's make your first one. But before we make your first one, I'm just gonna give some additional context of what we're actually typing in here. So when I ask get work tree list, it returns every work tree that's connected to my current repository.

And this is the directory that that code is on on my machine. So each of these directories are where the files live for each corresponding work tree. And then here, you can see each of these are the branches that are associated with each work tree.

So you can see here, as we talked about earlier, each work tree does have its own directory on your local machine. Because as it's building out a feature, it's going to be able to update those local files for the specific branch and not interact with other agents that are running, working in different directories. So now if I type in git status sorry, not git status.

If I type in git branch, you're going to see all of the branches that are currently associated with repository that I have. So everything that's teal is actually a branch that is open but in a different directory with a different work tree.

And here in this directory, I have main open as my branch. And then these white branches are branches that I have locally, but I don't have them open anywhere in a work tree.

Now, you can probably see a theme here with naming. I like to have all of my working directories start with the name of the project. So then when I type l s into my machine, all of the work trees that I currently have are going to show up in one place, so it's pretty easy to find.

And then I like to name each work tree corresponding to the specific feature that I wanna implement. So that way, when I'm working with multiple terminals open and I'm working on multiple features at once, I'm not going to get confused what's happening where. And I'm also going to remember the exact feature that I'm working on and make sure that that feature doesn't overlap with any of the work that I'm doing on another branch.

And then once that feature is done, I'm going to be able to commit that work and then merge it to either your staging branch or your main branch or whatever workflow you have set up. Now that's just how I like to name things. Obviously, you can name this however you want.

This is just a method that I found was really helpful. Now that we've gone over that, it's time to actually create your first work tree. So in your directory, you're going to type in git work tree add.

Now we're gonna go back one directory because you wanna get out of this project. So now you have a whole another folder that's being created just back one directory so they don't overlap.

So I'll name it AI agent. And for this work tree, we're just going to implement a new endpoint. So I'll make it endpoint.

And now we're going to create a new branch. So if I do dash b, and I'll do new endpoint.

And then I'm going to specify what branch I want to create this branch off of. So I currently work with and staging, and I'm updating staging right now. So I'm just going to make this.

So I'm just gonna make this branch off of my staging branch. So we'll do origin dash staging. If you're currently working with just a main branch, you can do origin forward slash main.

And now you can see it's preparing the work tree. It created a new branch, and it's set to track against my staging branch.

And the head is now at the last commit that I had to my staging branch. So now we can type again git status. Sorry.

Not git status. I keep doing that. We're gonna type in git branch.

And here, you can see I have a new branch created. So this is my new endpoint, and it's teal because it's connected to a new work tree that I just created.

So if I type in get work tree list, we should be able to see this new work tree as part of the list. And you can see it here, the AI agent endpoint. Now let's walk through an example of actually using these work trees in practice so you can get a feel of what an optimized workflow look like and how you can adjust your current coding workflow.

So here you can see I have a few different work trees and branches already set up. And we're going to work through two of them. So first, let me open a new tab here.

And I'm gonna c d back one directory because I was in that main branch directory. And if I type in l s, it's gonna show me all of the directories in this folder. And just showing why I like naming all of my work trees with the name of the project in the beginning because now you can see all of the work trees I have are conveniently located in one spot.

So now let's CD into the dashboard feature. And that's gonna be one thing that I'm gonna be working on.

Now I'm gonna open up Codex. I've recently been using Codex a lot more often than Claude. It's gonna work exactly the same if you're using Claude.

Either way, your preferred LLM here. And now I opened up my codec session within my dashboard creation work tree.

Now I already prewrote out what step I wanted to add in to this feature just so you didn't have to watch me type this all out because it's pretty long.

But, basically, it's just adding in the capability for this dashboard to interact with DeFi Lama.

So that's the next feature that I'm adding into this dashboard. And since this is a back end update, I know that it's not going to affect the other feature that I'm gonna be working on in my next work tree, which we'll go over in a second. But here, you can see it's just specifying that I want to add in market context for the dashboard that I'm creating, and it's gonna give some detailed information so my agent knows exactly what it needs to do for this new dashboard feature in my AI agent project.

Now while that's running, I'm gonna open up a new tab, and we're gonna split screen this so we can keep tabs on what's going on on both sides here.

Okay. So now I'm gonna get out of this work tree, and we'll l s again.

And I'm going to also work on the HubSpot access that I'm creating for my AI agent. So we'll see you over there.

And then once again, I'm gonna open up Codex.

Now here, you can see why I like to name the directories the same as the feature that I'm implementing. Because you can see in this terminal, it's labeled HubSpot access. And this terminal is labeled dashboard creation.

So now here's a good example of why you wanna make sure you're always reading what Codex or Claude or whoever is prompting you to do next.

Because now this is saying to switch to a new branch for just DeFi Llama, which I want this to actually be part of the dashboard that I'm creating and have this all in one branch and one feature. So let's just double check and make sure this is on the correct branch.

So this is on the dashboard creation branch. So we're just gonna tell this no. I don't want a separate branch.

I want this altogether.

So we'll say stay on the Okay. So now we have our dashboard working on our left side.

And then here, I'm going to work on updating the UI for the HubSpot access of this agent. Now I already have this running locally, so I'm actually gonna pull this up. And this, I ran locally directly from this AI agent HubSpot access directory.

So I know that this is connected to my HubSpot access branch and this HubSpot access work tree. So as I update on this side, my UI is going to update. So one of the simple changes that I wanna make here is just adding a select all or unselect all box in the HubSpot card.

So we're just gonna add that.

Okay. So we're gonna leave this UI on the back. We're going to have our HubSpot agent running, and then we're also going to have our dashboard running.

So usually, if I have both of those running and I still have some time left, I'll probably switch over to another branch and start working on that too. But for this video, just for simplicity, you can see that we have two different workflows happening at once with two different features that don't overlap each other.

And they're existing in two different directories here. So the local code that is being worked on by each agent is going to be separate, stored in separate locations on my computer. And that's what's enabling both of these to be working together.

So once we have these updates, I'm going to show you how to push and merge when you get to Git. But for now, we're just gonna let these run, and then I'll speed everything up in the video and show you the next steps. So now you can see that both of these sessions have completed.

So if we look at the right session, you can see that the UI update has been made. So if I go back to what I'm running locally, you can see here is my select all button that has been added, and we can test it out.

It works as expected. So this side's good to go. Now on this side, it was a much more complex addition by adding the DeFi Lama integration into the dashboard.

So this, I'm going to have to write some tests and actually test it out on my side to make sure everything works before I actually commit this. But for this video, we'll skip ahead. So I'm going to open another tab on both sides, and you can see I'm in the respective folder for each of these work trees.

And I'm just gonna type in git status to show that these have worked on two different local directories, and the work has not affected each other. So if I type in git status on each side, you can see the updates are very different.

So on the left, we have mainly all back end updates working with our PHP files. And then on the right, we have our front end updates with our HTML CSS files.

So that's what it looks like with GitHub. And if I commit this change, Now I'll commit this change, and I'll open GitHub so you see what it looks like.

So I'll go to my AI agent project, and we're going to go to the branches. And this one, I'm working on the HubSpot access branch, and you can see that there was a commit just now.

And I'm working with my staging environment, so I'm just gonna make a PR to staging and be able to merge this new update. And you can see each of these are working on their own branch, and you'll be able to merge each feature into its next branch once you commit and push to GitHub.

And just to be aware, there may be merge conflicts that you're going to have to resolve if you're working with multiple agents and some of the files do happen to overlap. So that's one thing to keep note of.

Now now that you're able to see an example workflow in action, let's talk about some more advanced patterns when using WorkTrees with Claude or Codex. So first, we'll start with the MD file in Workspaces. So with Claude, you have a root Claude MD.

With Codex, you're going to have an agents dot MD. So let's just show an example here. I'm going to open my code, and I have my agents m d file for this project to work with Codex.

And you can see you can see that it just defines additional instructions about this project to be able to give it as context for the LM that I'm working with.

So because this exists, this means that the project context is automatically available in every single work tree that you set up without any extra setup. So one MD file for agent context is going to benefit all of the agents that you have running in multiple sessions. But where this gets interesting is you can add a Worktree specific MD file for tasks that need additional context.

So you just create another Claude MD or agents MD if you're working with codex in the work tree root with additional context. And this gives scoped context for scoped work when you're working with a specific feature in a work tree.

Now the next pattern is my favorite one, which is agent versus agent comparison. In my opinion, the most useful work tree pattern is actually not parallelism, but comparison with multiple agents.

So how this works is you give two agents the exact same task in two separate work trees. So you review both outputs, and you pick the better one and discard the other.

This is really useful for architecture decisions where there are multiple valid approaches, and you wanna see both implemented before committing to a final design. So this essentially gives you a free architecture exploration because the cost of exploring two approaches is not double the time in this case.

It's the same time with half the opportunity cost. Now the next pattern I'm going to talk about is using TMux with your agent. So if you run multiple agents regularly, TMux is worth learning.

It lets you create named sessions for each work tree, detach, and reattach without losing the agent's context. And you can see all of the active sessions at a glance.

So let me go over the basic setup. I'll navigate back to my terminal, and you can check to see if you have TMUX on your computer here. If you don't, you can just install with brew install.

Brew install TMux, and you'll be good to go. Now we're going to create a named session for each of these workflows.

So we'll do TMux, new session.

And then we're gonna name the session. So we'll name this one HubSpot.

And then you're gonna specify where you want this session to exist based off of the current directory that you're in. So I'm currently in my AI agent directory.

I want it to exist within the AI agent HubSpot access directory. So I'm going to do dash c. And we're going to go back and then do AI agent.

Okay. So now you can see it auto created a persistent session here inside my AI agent HubSpot access. So now if I go back to my AI agent directory, I can type in TMux LS.

And that's going to show me all of my active sessions and whether it's attached or detached. So now with this running, your agent sessions persist even if you close a terminal.

So you can check-in on any agent at any time. And this is a setup that I'm moving towards in my day to day workflow. So you have a named Teamwork session per Work Tree, each with its own Clogcode instance and each on its own task.

Now let's just recap when to use a Worktree and when not to. So I'll use a Worktree if there are two or more tasks that I wanna do today that don't share the same file. Or if the task is risky enough that I wanna see two different approaches before actually committing to one, then, again, I'll use a work tree.

Now if a single task spans the whole code base, then I'd recommend just sticking to a single session that day. And if the task is more of an exploratory task, then, again, I'd say keep it to a single session and let the agent be able to roam throughout the code base.

But overall, WorkTrees have helped me optimize my daily workflow and just become a lot more efficient. So I hope it helps you as much as it helped me. Let me know any questions or comments you have below, and stay tuned for more AI videos.

The Hook

The bait, then the rug-pull.

Every AI coding session has dead time — the stretch where your agent is thinking and you have nowhere useful to put your attention. The obvious fix is to open a second session on a different task, but do that in the same directory and you get something worse than idle: two agents silently overwriting each other's work with no idea why the code keeps breaking. Git worktrees are the structural fix.

Frameworks

Named ideas worth stealing.

04:16concept

Worktree naming convention

Prefix every worktree directory with the project name so all worktrees appear grouped when you run ls in the parent directory.

Steal forAny multi-agent project setup

16:23model

Agent vs. agent comparison

Give two agents the identical task in two separate worktrees. Review both outputs and discard the loser. The total wall-clock time is the same as a single run, but you get to see two architectural approaches before committing.

Steal forArchitecture decisions, refactor approaches, any high-stakes implementation choice

15:11concept

Scoped context files

Root CLAUDE.md or agents.md provides global project context to every worktree automatically. Create an additional worktree-level MD file for feature-specific instructions without polluting the main context file.

Steal forAny Claude Code or Codex project with multiple parallel features

17:15concept

TMux per-worktree sessions

Run tmux new-session -s <feature-name> -c <worktree-path> for each agent. Sessions persist after terminal close. tmux ls gives an at-a-glance view of all active agents.

Steal forLong-running agent tasks, overnight runs, context switching between many features

CTA Breakdown