Great! I'm ready to help you learn git worktrees. This is a really useful feature for your use case of running multiple agents in parallel on different branches.

Let's start by setting up the demo repository. First, run those cleanup and clone commands:

!rm -rf Hello-World agent-bugfix1 agent-bugfix2
!git clone https://github.com/octocat/Hello-World

After that runs successfully, we'll change into the repository directory. Let me know once you've run this and we'll take the next step!

Perfect! Let's start with the fundamentals of git worktrees.

What is a Git Worktree?

Normally, a git repository has one working directory where you check out branches. If you want to work on a different branch, you have to switch branches with git checkout, which changes all the files in your working directory.

A worktree lets you have multiple working directories for the same repository. Each worktree can have a different branch checked out. This means you can:

• Work on multiple branches simultaneously without switching
• Keep each branch's files completely separate
• Perfect for your use case: run multiple agents on different branches in parallel!

The Main Worktree

Right now, you're in what's called the main worktree (or primary worktree). This is the original Hello-World directory you cloned. Let's see what we have:

!git worktree list

Run this command. It will show you all worktrees associated with this repository. Right now, you should only see one - the main worktree on the master branch.

Exactly! That's a great observation. You've been using a worktree all along - you just didn't know it had that name!

The main worktree is indeed just the root of your repo. When git added the worktree feature, they didn't change how the main repository works at all. They just made it possible to create additional worktrees that link back to the same git repository.

So the mental model is:

• Before worktrees existed: You had one folder with your repo, and you'd git checkout to switch branches
• With worktrees: That original folder is still there (the main worktree), but now you can create additional folders that are linked to the same .git directory

Think of it like this: the main worktree is your "home base," and additional worktrees are like "branch offices" - they all share the same git history and configuration, but each can work on different branches independently.

Ready to create your first additional worktree?

Great! Let's break down both scenarios:

Creating a Worktree with a NEW Branch

git worktree add ../agent-bugfix1 -b bugfix1

This does two things:

1. Creates a new branch called bugfix1 (the -b flag means "create branch")
2. Creates a new directory at ../agent-bugfix1 with that branch checked out

The new branch starts from wherever you currently are (in this case, master).

Creating a Worktree from an EXISTING Branch

git worktree add ../agent-bugfix2 bugfix2

This assumes the branch bugfix2 already exists. It:

1. Creates a new directory at ../agent-bugfix2
2. Checks out the existing bugfix2 branch there

No -b flag needed since the branch already exists.

Key Points

• The path (../agent-bugfix1) is where the new worktree folder will be created (relative to your current location)
• You can only check out a branch in one worktree at a time - git won't let you have the same branch active in multiple worktrees simultaneously

Ready to try creating your first worktree?

Exactly! You've just hit that restriction. Git is telling you: "Hey, bugfix-1 is already checked out in the main worktree (/app/data/Hello-World), so I can't check it out in another worktree too."

This is actually a safety feature - it prevents conflicts from having the same branch active in multiple places at once.

To fix this, you have two options:

Option 1: Switch your main worktree back to master, then create the worktree with bugfix-1:

!git checkout master
!git worktree add ../agent-bugfix1 bugfix-1

Option 2: Create the worktree with a new branch instead:

!git worktree add ../agent-bugfix1 -b bugfix-1-agent

Which approach makes more sense for your use case of running agents in parallel?

Perfect! Now you have your first additional worktree. Let's see what you've got:

!git worktree list

Run this to see both worktrees - your main one on master and the new one on bugfix-1.

Great question! This is the key insight about worktrees.

You're right - they're not two separate clones. They share the same .git directory. Let's look:

!ls -la Hello-World/.git

!ls -la agent-bugfix1/.git

Run both of these. You'll see something interesting about the .git in the worktree folder - it's different from the main one.

Notice the size difference!

• Hello-World/.git is a directory (4096 bytes)
• agent-bugfix1/.git is a file (59 bytes)

Let's see what's inside that file:

!cat agent-bugfix1/.git

This will show you the secret - it's just a pointer back to the main .git directory!

There it is! The .git file in agent-bugfix1 is just a pointer that says "my real git data is at /app/data/Hello-World/.git/worktrees/agent-bugfix1".

So here's what's happening:

• Hello-World/.git/ contains the actual git repository (all commits, history, config, etc.)
• agent-bugfix1/.git is just a tiny text file pointing back to the main .git
• All worktrees share the same commit history, branches, and remotes

This means:

• If you commit in agent-bugfix1, that commit goes into the shared repository
• You can see branches created in one worktree from all other worktrees
• Much more disk-efficient than cloning multiple times!

Want to see this in action by making a change in the worktree?

Exactly! Let's change into the worktree directory:

os.chdir('agent-bugfix1')

After you run that, check where you are and what branch you're on:

!pwd
!git branch

Perfect! You're now in the agent-bugfix1 worktree on the bugfix-1 branch (the * shows which branch is active).

Let's make a change here to simulate what an agent might do. Create a new file:

!echo "Bug fix #1: Fixed critical issue" > bugfix1.txt
!git status

This will show you the new file as untracked. What do you think will happen if we look at git status back in the main worktree?

Great! You've committed a change on the bugfix-1 branch in the worktree. Now let's go back to the main worktree and see what it looks like there:

os.chdir('../Hello-World')

Then check:

!pwd
!git branch
!ls

What branch do you think you'll be on, and will you see the bugfix1.txt file?

Exactly! You're on the master branch, and bugfix1.txt only exists on the bugfix-1 branch.

But notice something important - you can see bugfix-1 in the branch list (with the + symbol). That + means it's checked out in another worktree. The commit you made in the agent-bugfix1 worktree is now part of the shared repository.

Want to verify that commit exists? Try:

!git log bugfix-1 --oneline

This will show you the commit history of the bugfix-1 branch, including your new commit, even though you're currently on master.

Exactly right! Let's verify that:

!git checkout bugfix-1

Try it and see what error message git gives you.

Yes, exactly! You've simulated three agents working independently:

1. Main worktree (Hello-World/) - worked on update-readme branch, modified README
2. agent-bugfix1 - worked on bugfix-1 branch, created bugfix1.txt
3. agent-bugfix2 - worked on bugfix-2 branch, created bugfix2.txt

All three are completely independent - they didn't interfere with each other, and each has their own changes committed to their own branch.

Let's verify all three branches exist with their changes:

!git branch -v

This will show all branches with their latest commit messages. What do you want to explore next - maybe merging these branches, or cleaning up worktrees?

Yes! Now let's clean up the worktrees. Once you've merged the changes, you typically don't need those separate worktrees anymore.

First, let's see what worktrees you have:

!git worktree list

Then to remove a worktree, you use:

git worktree remove <path>

Try removing one of them. Which one do you want to remove first?

Almost! The worktree directories are removed, but the branches still exist. Check:

!git branch

You'll see bugfix-1, bugfix-2, and update-readme are still there. Do you want to delete those branches too, or keep them?

Exactly! You've got it perfectly.

Before worktrees:

• One repo = one branch at a time
• All terminal tabs see the same branch
• Switching branches in one terminal affects all others
• Can't run multiple agents in parallel on different branches

With worktrees:

• One repo = multiple worktrees = multiple branches simultaneously
• Each terminal tab can cd into a different worktree
• Each worktree is completely independent
• Perfect for running multiple agents in parallel!

So your workflow would be:

1. Create worktrees for each agent task: git worktree add ../agent-feature-x -b feature-x
2. Open separate terminals, cd into each worktree
3. Run your agent (e.g., claude) in each terminal
4. Each agent works independently on its own branch
5. When done, merge branches back to main and clean up worktrees

The key benefit: no interference - each agent has its own isolated workspace with its own branch checked out.

Is there anything else about worktrees you'd like to explore before wrapping up this tutorial?

Correct! Untracked/uncommitted files are not copied to new worktrees.

Each worktree only contains:

• Files that are committed to the branch it has checked out
• Any new files you create in that specific worktree

So in your case:

• temp_file.txt exists only in the main worktree (untracked)
• The new-feature worktree doesn't have it
• The new-feature worktree has README, bugfix1.txt, and bugfix2.txt because those were committed to master (which new-feature branched from)

This is actually perfect for your agent use case - each agent's workspace is clean and only contains committed code. Any temporary files, logs, or work-in-progress that an agent creates stays isolated in its own worktree.

Does this complete your understanding of worktrees, or is there anything else you'd like to test?