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

# Worktrees

> Give a chat its own git worktree so you can work on a branch without disturbing your main project folder.

A **worktree** is a separate checkout of your project's git repository, on its own branch. Start a chat in one when you want Kombai to work on a branch while your main project folder stays untouched, or to run several chats on different branches of the same project at once.

> [!NOTE]
>
> Worktrees are available only in the desktop app, for a folder that is the root of a git repository.

## Start a chat in a worktree

1. On the home screen, select your project. A **Worktree** chip appears next to the project picker.
2. Click **Worktree** to turn it on. It changes to **Worktree from `<base>`**.
3. To start from a different branch, click the chip and pick a base branch. The list puts `dev`, `main`, and `master` first, then the rest newest first, with a search box at the bottom.
4. Send your message. The chip shows **Preparing worktree…** while Kombai creates the worktree and its branch, then the chat opens there.

If creating the worktree fails, git's message appears under the project bar and your message stays in the input box.

To turn the chip off before you send, hover over it and click its  icon (**Don't use a worktree**). The chip starts off in every new chat. Kombai remembers only your last base branch for each project.

The chip is unavailable in two cases:

* **The repository has no commits.** Make a commit first.
* **The folder is already a worktree.** You can't start a worktree from another worktree.

> [!NOTE]
>
> If your project already has `node_modules` installed and its lockfile matches the worktree's, Kombai copies them into the new worktree so the first build doesn't reinstall. To turn this off, use **Seed dependencies** in [Settings](#manage-worktrees-in-settings).

## Work in a worktree chat

A strip along the top of the chat input names the worktree: **Worktree `<branch>` from `<base>`**. It also has:

* The  **Create PR** button, which opens the [pull request panel](#create-a-pull-request). Once the chat has a pull request, a link to it (for example, **PR #42**) replaces the button.
* The  icon, a menu with **Open in Finder**, **Open in Terminal**, and **Copy path**.

If merging in the base branch leaves conflicts, the strip shows how many files conflict and lists them. Click **Ask Kombai to resolve** to have Kombai fix them.

### Review the branch's changes

In a worktree chat, the [Changes](/get-started/navigating-the-desktop-app#right-panel) view adds a **This branch** scope, selected by default. It shows everything that changed since the branch left its base, including untracked files. Use **Compare against `<branch>`** to compare with a different branch.

## Create a pull request

Click the  **Create PR** button on the strip. The button is hidden when the repository has no remote or the branch has conflicts.

The panel has a **Title** (defaulting to the chat's title), a **Base** branch, and a **Draft** checkbox. Below them, Kombai checks:

* **Required:** whether the branch is up to date with its base, and whether the repository has a GitHub remote. If the branch is behind, click **Sync with `<base>`** to merge in the latest changes.
* **Where it opens:** whether the GitHub CLI (`gh`) is installed and signed in, and whether a pull request is already open.

Then click the confirm button. Its label depends on `gh`:

* **Create pull request:** if `gh` is installed and signed in, Kombai creates the pull request in the chat. The request appears as a card, and the chat switches to Code mode if needed.
* **Push and open compare page:** otherwise, Kombai pushes the branch and opens GitHub's compare page in your default browser, where you finish creating the pull request.

## Close or remove a worktree

When you close or delete the last chat in a worktree, Kombai asks whether to **Keep** or **Remove** it. The dialog shows uncommitted and unpushed changes, any pull request, and the folder path. **Keep** is the default. Check **Remember my choice** to skip the dialog next time, or set a default in [Settings](#manage-worktrees-in-settings).

> [!WARNING]
>
> Removing a worktree deletes its uncommitted changes. Committed work stays on the branch.

Removing a worktree from this dialog always keeps its branch. To delete the branch too, remove the worktree from the [sidebar](#worktrees-in-the-sidebar) or [Settings](#manage-worktrees-in-settings) and check **Also delete branch `<branch>`**. The label warns you if commits that aren't on the base would be lost.

## Worktrees in the sidebar

A project with worktrees lists them nested under its row in the sidebar, each with its own chats, and labels the project's own chats **Threads**. Hover over a worktree row to:

* Click the  icon (**Start a new thread in `<branch>`**) to start a new chat in that worktree. Its chip reads **Worktree `<branch>`** and can't be turned off or changed.
* Click the  icon (**More options**), or right-click the row, for **New thread here**, **Open in Finder**, **Open in Terminal**, **Copy path**, and **Remove worktree…**.

**Remove worktree…** is unavailable while a chat in the worktree is open. **Open in Terminal** is missing if Kombai finds no terminal app, as on some Linux desktops.

## Manage worktrees in Settings

Open [Settings](/account/settings) and go to **Worktrees**, under Preferences:

| Setting | What it does | Default |
| - | - | - |
| **Branch prefix** | The prefix for new worktree branches, named `<prefix>/<name>`. | `kombai` |
| **Worktree location** | Where new worktrees are created: **Outside the project (\~/Kombai/worktrees)** or **Inside the project (.kombai/worktrees)**. On Windows, the paths use backslashes. Existing worktrees stay where they are. Inside the project, Kombai hides them from git and from its own file lists, but your other tools may still see them. | Outside the project |
| **When a worktree's last chat closes** | **Ask**, **Keep the worktree**, or **Remove it**. **Remove it** applies only to a worktree with no uncommitted changes; Kombai always asks for one that has them. | Ask |
| **Seed dependencies** | Copies the project's installed `node_modules` into a new worktree when its lockfile matches. | On |

Below the settings, **This project's worktrees** lists each worktree with its branch, base, and age. Expand a row to see its folder and size, or click its  icon (**More actions**) for **New chat**, **Open in Finder**, and **Remove**. **Remove** is unavailable while a chat in that worktree is open. A worktree whose folder was deleted outside Kombai shows **Folder deleted** and a **Remove** button.

On Windows and Linux, **Open in Finder** in the sidebar and Settings menus reads **Open in File Explorer** or **Open in File Manager**.

## If a worktree's folder is missing

If you open a chat whose worktree folder was deleted, Kombai offers:

* **Recreate:** check out the same branch again, so you can keep working.
* **Open Read-Only:** open the chat without a folder to edit.

If the branch no longer exists, the chat opens read-only.

## What a worktree chat shares with its project

A worktree chat is listed under its parent project's name throughout the app, with the branch shown beside it.

* **Shared with the project:** [Memory](/context/memory). The worktree's Memory setting reads **Shared with `<project>`.**
* **Copied into the worktree:** the tech stack (unless it's saved in the repository), code settings, and the selected design system. Kombai copies them once when it creates the worktree, so changing them in a worktree chat doesn't change the project's.
* **From git:** anything committed to the repository, such as [rules](/features/rules), comes with the checkout.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.