Worktrees

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.

​

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.

​

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. 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 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. Removing a worktree from this dialog always keeps its branch. To delete the branch too, remove the worktree from the sidebar or 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 and go to Worktrees, under Preferences: 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. 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, comes with the checkout.