Git Worktrees for AI Agents: Commands and Pitfalls

What is a git worktree?

A git worktree is a working directory that is linked to an existing repository and checks out its own branch. Your normal clone is the main worktree; every git worktree add creates a linked worktree in another folder. All of them share one .git object store, so commits, branches and remotes are the same everywhere, but each folder has its own files, its own index and its own HEAD.

Compared with a second git clone, a worktree is faster to create, uses less disk because history is shared, and a commit made in one worktree is immediately visible from the others. Compared with switching branches, nothing is stashed and nothing is interrupted.

Why do AI coding agents need git worktrees?

AI coding agents need worktrees because they edit files directly and run for minutes at a time. Two agents in one folder overwrite each other's edits, share one staging area and fight over build output. A worktree per agent gives each one an isolated copy on its own branch, which is what makes running agents in parallel safe and each result reviewable as a clean diff in diff review.

Several agents, one folder

Edits collide in the same files
One branch mixes every agent's changes
You cannot discard one agent's work alone

One worktree per agent

Each agent edits its own copy
Each result is a branch with its own diff
Discard one by removing its worktree

How do I set up git worktrees for AI agents, step by step?

1
Check your git version
Run git --version. git worktree has been part of git since version 2.5, so any current install works.
2
Update the base branch
From your main checkout run git fetch origin so new worktrees start from the latest origin/main.
3
Create one worktree per agent
Run git worktree add ../myapp-auth -b feat/auth origin/main. That creates the folder ../myapp-auth with a new branch feat/auth started from origin/main. Repeat with a new folder and branch for every agent.
4
Bring the gitignored files
A new worktree is a clean checkout: node_modules, .env and build caches are missing. Install dependencies and copy the local files each agent needs.
5
Start the agent inside the worktree
cd ../myapp-auth and start the agent there, for example claude or codex. The agent's working directory is the worktree, so its edits stay there.
6
Review and merge the branch
Review with git diff origin/main...feat/auth, run the tests, then push the branch and open a pull request, or merge it locally.
7
Remove the worktree when you are done
Run git worktree remove ../myapp-auth, then git branch -d feat/auth if the branch is merged. Run git worktree prune if you ever deleted a worktree folder by hand.

Which git worktree commands do I actually need?

Four commands cover almost everything: add, list, remove and prune. The rest are for edge cases.

Command	What it does
`git worktree add <path> -b <branch> [<start>]`	Creates a folder with a new branch, started from `<start>` (default: current `HEAD`)
`git worktree add <path> <existing-branch>`	Checks out a branch that already exists, if no other worktree has it
`git worktree add --detach <path> <commit>`	Checks out a commit without a branch, for quick experiments
`git worktree list`	Shows every worktree with its path, commit and branch
`git worktree remove <path>`	Deletes a clean worktree folder and its metadata; add `--force` to drop uncommitted changes
`git worktree prune`	Cleans metadata for worktree folders that were deleted by hand
`git worktree move <path> <new-path>`	Moves a linked worktree to another folder
`git worktree lock <path>`	Protects a worktree on a removable or network drive from being pruned

git worktree cheat sheet

git fetch origin
git worktree add ../myapp-auth -b feat/auth origin/main
git worktree add ../myapp-tests -b test/checkout origin/main
git worktree list
# ...agents work, you review and merge...
git worktree remove ../myapp-auth
git branch -d feat/auth

What are the common git worktree pitfalls?

A branch can live in only one worktree. fatal: 'main' is already checked out means another worktree has it. Create a new branch per worktree instead.
Gitignored files are missing. .env, node_modules and caches do not come along. Budget setup time or automate the copy.
Ports and shared services collide. Two dev servers on port 3000 fail. Give each worktree its own port and, if needed, its own test database.
Worktrees inside the repo confuse tools. A worktree nested in the main folder shows up in searches and watchers. Keep worktrees in a sibling folder or a gitignored directory.
Deleting the folder by hand leaves metadata. Git still thinks the branch is checked out. Run git worktree prune.
`--force` loses work. git worktree remove --force discards uncommitted changes. Commit or check the diff first.
Disk use adds up. History is shared, but each worktree has its own files and dependencies.

Let Tallos handle the worktrees. Every workspace is one, created and cleaned up for you.

Get Tallos →

How does Tallos automate git worktrees?

Tallos is worktree-native: every task you start becomes a workspace, and every workspace is a real git worktree with its own branch, files and agent sessions. You never type git worktree add, but you can always drop to a terminal and use plain git inside any workspace.

Background creation. Tallos runs git fetch and git worktree add in the background and shows progress in the new tab; you keep working meanwhile.
Start-from picker. Branch off the base branch, another local branch (to stack on a PR in review), a specific commit, or a remote branch Tallos fetches for you.
Branch names. Derived from the workspace name, or from a linked GitHub PR, Linear, Jira or GitLab item. Set your own under Advanced → Branch name.
Gitignored files. List files to copy in .worktreeinclude at the repo root, and configure shared paths per repository in Settings → Repository.
Cleanup. Deleting a workspace removes the folder and the branch after confirmation. If git keeps a branch because it may have unmerged commits, Tallos lets you review it.
Your own worktrees. Worktrees made with git worktree add outside Tallos can be shown in the sidebar, and a worktree removed from the CLI is cleaned from Tallos on the next refresh.

Step	Plain git	Tallos
Create	`git worktree add ../dir -b branch origin/main`	New workspace
Choose the starting point	Pass `<start>`	Start-from picker
Copy `.env`	By hand	`.worktreeinclude`
Launch the agent	`cd` + agent command	Agent picked in the same dialog
Review	`git diff`	Diff view with line notes
Remove	`git worktree remove` + `git branch -d`	Delete workspace

The same worktree lifecycle, by hand and in Tallos

See it in practice in how to run multiple Claude Code sessions, or read the parallel workspaces feature page. New to the vocabulary? The glossary defines worktree, workspace and base ref.

Frequently asked questions

What is the difference between git worktree and git clone?

A clone copies the whole repository, history included. A worktree is an extra working folder that shares the original repository's history, so it is faster to create and uses less disk.

Can two worktrees use the same branch?

No. Git allows a branch to be checked out in only one worktree at a time. Create a new branch for each worktree.

How do I delete a git worktree?

Run git worktree remove <path>. If you already deleted the folder by hand, run git worktree prune to clean up the leftover metadata.

Why is my .env file missing in a new worktree?

Worktrees only contain tracked files. Gitignored files such as .env and node_modules must be copied or reinstalled; Tallos can copy them automatically with a .worktreeinclude file.

Where should I put git worktrees?

Outside the main folder, for example in a sibling directory, so editors, watchers and searches do not pick them up twice.

Does Tallos use real git worktrees?

Yes. Every Tallos workspace is a standard git worktree, so git status, git rebase and any other git command work inside it.

Git worktrees for AI agents: commands, pitfalls and automation