> For the complete documentation index, see [llms.txt](https://docs.nimbalyst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nimbalyst.com/developer-features/worktrees.md).

# Worktrees

Use git worktrees in Nimbalyst to run AI coding agents on several branches at once, each with its own directory, session, and diff to review.

A git worktree gives an AI session its own branch and its own working directory, isolated from your main checkout. Use a worktree when you want an agent to build a feature, try an experiment, or investigate a branch without touching the code you are working in. Worktrees require [Developer Mode](/developer-features/turn-on-off-developer-mode.md) and a git repository.

For background on why worktrees matter when several agents are running at once, see the [git worktrees guide](https://nimbalyst.com/blog/git-worktrees-for-ai-coding-agents-complete-guide/).

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FNVzHlMBm7rppje3MCpvN%2FWorkTrees.png?alt=media&amp;token=4a26d4c9-1596-48c2-9816-ef18431f2fc4" alt="An agent session running in a worktree, with the transcript&#x27;s edit cards in the center and the worktree&#x27;s uncommitted files, commit box, and Merge to master button on the right"><figcaption><p>An agent session in its own worktree: edits happen on an isolated branch, with commit and merge controls in the right panel.</p></figcaption></figure>

### Creating a Worktree

There are three ways to start a worktree session:

1. From the menu beside **New session** in the title bar, choose **New Worktree** (**Cmd/Ctrl+Alt+W**). This starts an isolated AI session on a new branch.
2. From a Tracker item, choose the worktree action to launch an isolated session with that item linked as its context.
3. From Pull Request mode, choose **Open in Worktree** to check out the pull request branch and start a session inside it. See [Pull Request Reviews](/developer-features/pull-request-reviews.md).

### Working in a Worktree

* Each worktree has its own file system state, so changes never interfere with your main branch or with other worktrees.
* Review the session's edits, commit them, and merge the branch back from the panel next to the session.
* Rebase a worktree even with uncommitted changes; Nimbalyst auto-stashes them for you.
* Use the worktree's terminal button to open a [terminal](/developer-features/terminal-window.md) scoped to that worktree's directory.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FCDUBFJmiFxdftHxOq2WI%2FWorktree%20with%20Files.png?alt=media&amp;token=85aab04a-a2e0-493b-9e63-1ac8d0337cfa" alt="A file from a worktree session open in the editor with green added lines and Revert and Keep buttons, next to the worktree&#x27;s commit panel"><figcaption><p>Reviewing a worktree session's changes: open any edited file, then keep or revert the changes before committing.</p></figcaption></figure>

### Worktrees vs Workstreams

These are easy to mix up:

* A **workstream** groups related sessions. All of its sessions work in the same project folder on the same branch. See [Workstreams](/session-management/workstreams.md).
* A **worktree** gives a session its own git branch and folder, isolated from your main checkout.

Use a workstream to organize related sessions; use a worktree when a session's changes should stay off your main branch. A session in a worktree can also grow into a workstream, so the two combine.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nimbalyst.com/developer-features/worktrees.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.