# Work in a git worktree

> Give each agent its own branch and folder with a git worktree, so agents working at once never edit the same files.

Source: https://hivemind.griiken.com/guide/git-worktree/

Run two agents on one project without them editing the same files. Each gets a
<Tooltip tip="A second checkout of the same git repository in its own folder, on its own branch, so two agents never edit the same files." cta="Glossary" href="https://hivemind.griiken.com/guide/glossary/#worktree">worktree</Tooltip>:
its own folder and branch.

<AgentPrompt description="Paste this into your coding agent to set up a worktree with its own agent." page="git-worktree">{`
Set up a git worktree for a new task in this project, open it in Hivemind and start an agent there.

1. Check Hivemind is open on this project: \`hive ctl frames --json\` answers. If it exits 3, tell me to open Hivemind on the project and stop.
2. Ask me for a branch name for the task and which agent to use.
3. Make the worktree beside the project: \`git worktree add ../<project>-worktrees/<branch> -b <branch>\`. If the branch exists already, leave out -b. Do not delete or reset any branch.
4. Open it as a frame: \`hive ctl frame add --folder <full path of the worktree> --name <branch>\`.
5. Start the agent in it: \`hive ctl spawn --frame <branch> --agent <agent> --prompt "<the task I give you>"\`.

Check: \`hive ctl agents\` lists the new agent, and \`git -C <worktree path> branch --show-current\` prints the branch. Tell me the worktree path, its branch and the agent's tile id.
`}</AgentPrompt>

## Before you start [#before-you-start]

- The project is a git repository, opened in Hivemind.
- The repository has no submodules. Git worktrees do not support them.

## Make a worktree in the app [#make-a-worktree-in-the-app]

1. Open the project frame's ⋯ menu and choose **Worktree**.
2. Choose **Create new worktree**, type a new branch name, and press **create**.
3. Check: a new frame appears, nested under the project, named after the branch.
4. Select the new frame and press **2** to start your default agent there.
5. Check: the agent's tile shows the worktree's folder, not the project's.

Hivemind puts a new worktree in `../<project>-worktrees/<branch>`, beside the project. To open a
worktree that already exists, pick it from the same **Worktree** menu.

## Make a worktree in a terminal [#make-a-worktree-in-a-terminal]

1. Make the worktree with git:
   `git worktree add ../myproject-worktrees/fix-login -b fix-login`.
2. Open it as a frame: `hive ctl frame add --folder ~/src/myproject-worktrees/fix-login --name fix-login`.
3. Check: the command prints the new frame's id, and the frame appears on the canvas.
4. Start an agent in it: `hive ctl spawn --frame fix-login --agent claude --prompt "Fix the login redirect"`.

## Check it worked [#check-it-worked]

- `git worktree list` shows the new folder and branch.
- The agent's work lands on its own branch. `git -C <worktree> status` shows its changes.
- The project folder's own branch stays as it was.

## If it didn't [#if-it-didnt]

| You see | Do |
|---|---|
| `branch … is already checked out at …` | Another worktree uses that branch. Pick a new name, or open that worktree. |
| `repo has submodules` | Git worktrees do not support submodules. Use a separate clone instead. |
| No **Worktree** item in the frame menu | The frame is not on a git repository, or it is already a worktree. |

## Related [#related]

- [Run many agents at once](https://hivemind.griiken.com/guide/run-many-agents/): a tutorial with three worktrees.
- [Workspaces, frames and tiles](https://hivemind.griiken.com/guide/workspaces/)
- [Review an agent's changes](https://hivemind.griiken.com/guide/review/)

<LastValidated />