# How to use git worktrees for AI coding agents

A git worktree is a second working folder for the same repository, checked out on its own branch.
For AI coding agents, a worktree per agent means each one edits its own copy of the files, so
several can work in one repository at once without their changes mixing. Moontors, an agentic
development environment (ADE), can make, use and clean up a worktree for each session.

## By hand

```sh
# a branch and a folder for one agent's task, beside your checkout
git worktree add -b fix-login ../myapp-fix-login
cd ../myapp-fix-login
# start the agent here, then review and merge the branch as usual
git worktree remove ../myapp-fix-login
```

Two things to remember: files git doesn't track, such as `.env`, aren't in the new worktree, and a
worktree you forget to remove stays on disk with its branch.

## With Moontors

When the folder you pick in **Create session** is in a git repository, turn on
**Run in a new worktree**. Moontors then:

- makes a branch from your checkout's current commit, named from the session's title, such as
  `moontors/fix-the-login`;
- puts the worktree under `~/.moontors/worktrees/`, outside your own folders;
- copies in the untracked files your project lists, such as `.env`;
- starts the session there.

The card shows the repository and the branch, and the session's Git view opens on its worktree,
with its branch marked in the history and its changes beside it. When you're done, archiving the session removes the worktree. It asks first if
the worktree has uncommitted changes or commits that aren't pushed, and the branch stays whenever it
holds work. See [Worktrees](/docs/worktrees/) for the details.

## Things to know

- A worktree starts from the last commit, so your checkout's uncommitted changes aren't in it.
- Each worktree is a full copy of the files, so dependencies installed in your checkout aren't in it:
  the agent may need to install them first.
- You merge each agent's branch yourself, as you would a teammate's.

## Questions

### What is a git worktree?

A second working folder for the same repository, checked out on its own branch. Agents in separate
worktrees each edit their own copy of every file.

### Are my uncommitted changes in a new worktree?

No. A worktree starts from the last commit. Files git doesn't track aren't in it either, but for
those your project lists for Moontors to copy, such as `.env`.

### What happens to the worktree when I'm done?

Archiving the session removes it. Moontors asks first if it holds uncommitted changes or commits
that aren't pushed, and the branch stays whenever it holds work.

## Related

- [What is an agentic development environment (ADE)?](/docs/what-is-an-ade/)
- [How to run several Claude Code sessions in parallel](/docs/how-to/run-claude-code-sessions-in-parallel/)
- [A Conductor alternative for Windows and Linux](/docs/compare/conductor/)
- [An Orca alternative with Gemini CLI in structured views](/docs/compare/orca/)