# Git Worktrees for AI Coding Agents

A git worktree is an extra checkout of a repository, in its own folder and on
its own branch, that shares the same history. Giving each AI coding agent its
own worktree lets several agents work on one repository at the same time
without touching each other's files.

## Why agents need worktrees

- **No file conflicts.** Each agent edits its own copy of the code.
- **One branch per task.** Each worktree is on its own branch, so every task
  becomes its own commit history and pull request.
- **Clean tests.** An agent's tests and builds run against its own changes
  only.
- **Cheap.** Worktrees share one `.git` folder, so they are faster to create
  and smaller than full clones.

## The git commands

```sh
# Create a worktree on a new branch
git worktree add ../myapp-auth -b feat/auth

# Create a worktree for an existing branch
git worktree add ../myapp-fix fix/race

# List worktrees
git worktree list

# Remove a worktree when the branch is merged
git worktree remove ../myapp-auth
```

A branch can be checked out in only one worktree at a time.

## Things to plan for

- **Dependencies.** Each worktree has its own folder, so it needs its own
  `node_modules`, virtual environment, or build output. Install them when you
  create the worktree.
- **Ports and services.** Two dev servers on the same port will clash. Give
  each worktree its own port, or run services only where you need them.
- **Clean up.** Remove worktrees after merging, or they pile up. `git worktree
  prune` clears records of worktree folders you deleted by hand.

## Worktrees in Nana

Nana is a Windows terminal built around one worktree per agent:

- **Create from the sidebar.** **New Worktree…** asks for a name, a new or
  existing branch, and a location. Worktrees created outside Nana show up on
  their own.
- **Setup and teardown commands.** List commands in `.nana/worktree.json` and
  Nana can run them when it creates or removes a worktree:

  ```json
  {
    "setup": ["npm ci", { "name": "Start services", "command": "docker compose up -d" }],
    "teardown": ["docker compose down"]
  }
  ```

  The commands get `NANA_WORKTREE_PATH`, `NANA_WORKTREE_BRANCH`, and other
  variables. See [Projects](https://nana.areshk.dev/docs/features/projects.md#setup-and-teardown-commands).
- **Agent state per worktree.** Each worktree shows whether its agent is
  working, waiting for you, or done. See [AI agents](https://nana.areshk.dev/docs/features/ai-agents.md).
- **Review, commit, and pull request.** The Review tab shows the worktree's
  diffs. **Create PR** opens a pull request, and after merging Nana can remove
  the worktree. See [Git](https://nana.areshk.dev/docs/features/git.md).
- **From the command line.** `nana worktree list|create|checkout-pr|remove`
  manages worktrees from any shell, including on a remote server. See
  [Nana CLI](https://nana.areshk.dev/docs/features/nana-cli.md).

For a step-by-step setup with Claude Code, see
[Run multiple Claude Code agents in parallel on Windows](https://nana.areshk.dev/docs/guides/multiple-claude-code-agents-windows.md).