> ## Documentation index
> Fetch the complete documentation index at: https://haarness.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Work on a branch in a worktree

A worktree is a second checkout of your repository on its own branch. Use one to let the agent
work on a change while you keep your main folder as it is, or to run two tasks side by side. Each
worktree has its own Haarness server and its own chats.

## Create a worktree and open it

From inside your repository:

```sh
haarness worktree create review-fix --from main
haarness worktree open review-fix
```

`create` makes a new branch from `main` and checks it out in a new folder. It prints the folder's
path. `open` starts the terminal UI in that worktree.

Without `--from`, the worktree starts from the branch checked out in your main folder. Haarness
names the branch `haarness/review-fix-…` unless you pass `--branch`, and puts the folder inside
Haarness's data folder unless you pass `--path`. The new branch does not track a remote branch.
Worktrees need the project to be a Git repository.

To get the path for another tool:

```sh
cd "$(haarness worktree open review-fix --path-only)"
```

## See your worktrees

```sh
haarness worktree list
```

This lists each project with its main folder and worktrees, with their branches. `*` marks the
one you are in, and `missing` one whose folder is gone. Commands that act on a worktree take its
name, path or ID.

In the terminal UI, `/worktree` lists them and can create, open, reset and remove worktrees. In
Desktop, use the location button above the message box; see
[Work in a separate worktree](https://haarness.ai/docs/desktop/projects-and-panels.md#work-in-a-separate-worktree).

## Start over

```sh
haarness worktree reset review-fix --confirm
```

This moves the worktree's branch back to the ref it was created from, such as `main` as it is
now, and discards the commits made on it. Pass `--to <ref>` to reset to something else.

If the worktree has uncommitted changes to tracked files, reset stops. Add `--discard-changes` to
throw them away, and also `--remove-untracked` to delete untracked files. Ignored files are always
kept.

## Remove a worktree

```sh
haarness worktree remove review-fix --confirm --delete-branch
```

This deletes the worktree's folder. `--delete-branch` also deletes the branch, but only if Git
says it is merged; otherwise the branch is kept and the output says so.

If the worktree has uncommitted or untracked changes, removal stops. Add `--discard-changes` to
remove it anyway.

## What reset and remove will not do

- Act without `--confirm`.
- Act while a Haarness server is running in that worktree. Close its terminal UI, or stop the
  server with `haarness serve --stop --workspace <path>`.
- Remove the worktree you are standing in. Run the command from another folder.
- Touch folders you created yourself. Only worktrees made by Haarness can be reset or removed.

## Reference

| Command | Does |
| --- | --- |
| `worktree create <name>` | New branch and checkout; `--from`, `--branch`, `--path` |
| `worktree open <name>` | Open the terminal UI there; `--path-only` prints the path |
| `worktree list [--json]` | Projects, folders and worktrees (`ls` also works) |
| `worktree reset <name> --confirm` | Back to the starting ref; `--to`, `--discard-changes`, `--remove-untracked` (needs `--discard-changes`) |
| `worktree remove <name> --confirm` | Delete the checkout; `--discard-changes`, `--delete-branch` |

## Related

- [Find and resume a chat](https://haarness.ai/docs/cli/sessions.md)
- [Review changes](https://haarness.ai/docs/tui/review.md)