# Git worktrees for AI agents: commands, pitfalls and automation

> A git worktree is an extra working directory linked to the same repository, with its own branch and files but shared history. For AI coding agents, one worktree per agent means parallel sessions never edit the same files. You create one with `git worktree add`, list them with `git worktree list` and delete one with `git worktree remove`. Tallos creates and cleans up a worktree for every workspace.

- Canonical: https://runtallos.com/learn/git-worktrees-for-ai-agents
- Português: https://runtallos.com/pt/aprenda/git-worktrees-para-agentes-de-ia.md
- Updated: 2026-09-29
- Section: Learn

## Key facts

- One repository, many checked-out branches at once
- Core commands: add, list, remove, prune
- A branch can be checked out in only one worktree
- Every Tallos workspace is a real git worktree

## 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](https://runtallos.com/run-ai-agents-in-parallel) safe and each result reviewable as a clean diff in [diff review](https://runtallos.com/features/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_

```bash
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. → https://runtallos.com/signup

## 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](https://runtallos.com/learn/run-multiple-claude-code-sessions), or read the [parallel workspaces feature page](https://runtallos.com/features/parallel-workspaces). New to the vocabulary? The [glossary](https://runtallos.com/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.

---

**Run your agents in parallel with Tallos** — Claude Code, Codex, Gemini and 30+ agents — each in its own workspace, with squads, chat, terminals and review in one app. Uses the subscriptions you already have.

https://runtallos.com/signup (macOS 13+ · Windows 10+)