> ## Documentation Index
> Fetch the complete documentation index at: https://ai-development-environment.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Worktrees
> Manage primary and linked Git worktrees across every enrolled agent.
The **Worktrees** page at `/worktrees` is the busiest page in the product. It shows every primary and linked Git worktree across every enrolled machine, and gives each one a full set of Git operations, automation toggles, and links to the GitHub pull request or GitLab merge request, build, and AI work attached to it.
## Finding a worktree
* **Search** across branches, agents, repositories, tickets, and codebases.
* **Filter by agent** and **filter by repository**.
* **Filter by changes** narrows the list to **Dirty worktrees** or **Clean worktrees**. A worktree counts as dirty when it has staged or unstaged changes — the same rule behind its **Dirty** badge.
* **Filter by branch** can show only worktrees **Not on default branch**. Detached worktrees count when the repository's default branch is known; repositories whose default branch is unknown are excluded because they cannot be classified.
* Use **Group by agent** or **Group by repository** to choose the primary grouping. The other dimension remains visible on each worktree.
* Switch between **Card layout** and **Table layout**.
* **Refresh** re-reads status; **Fetch now** runs `git fetch origin` for eligible codebases.
Your search, changes filter, branch filter, grouping, and layout are saved in the browser and restored the next time you open the page. Filters combine, so you can show, for example, dirty worktrees that are also off their default branch. A saved agent or repository filter is ignored if that item no longer exists. The worktrees view inside an [app](/apps/app-detail) keeps its own saved filters, separate from this page's. The iOS Worktree Actions menu offers the same changes and branch filters for the current visit.
Each worktree shows its branch, path, base branch, agent, repository, upstream status, base freshness, nonzero commit counts, and — where they exist — its pull request, latest build, review decision, and comment count.
**Manage tags** creates reusable global tags with badge colors, and **Highlight** assigns a worktree a color that follows it everywhere — the Action Center, notifications, and run pages all pick it up. The palette includes lavender, maroon, brown, olive, and navy. Use the trash button beside **Highlight** to clear the current color.
### Status at a glance
| Indicator | Values |
| --------------- | -------------------------------------------------------------- |
| Upstream status | Ahead, behind, diverged, in sync, unpublished, detached |
| Base freshness | Current with an ahead count, or a count of commits behind base |
| Working tree | Dirty when staged or unstaged changes exist; otherwise clean |
| Review decision | Approved, changes requested, review required, or no decision |
## Creating a worktree
Pick the agent checkout that will own the worktree. Only online, compatible checkouts are offered.
* **New branch** — name a branch and pick a base.
* **Existing branch** — choose a local branch, an origin branch, or one that exists in both.
* **From ticket** — enter a Jira ticket key and let the branch name be derived from it, using the repository's Jira branch regex.
Select a base, or inherit the remote default.
The agent creates the worktree, applies the repository's preparation rules, and reports it back. If preparation fails, AIDE removes the incomplete worktree and removes only a branch created by that job.
## Per-worktree actions
| Action | Effect |
| -------------------------------- | --------------------------------------------------------------------------------- |
| **Pull** | Fast-forward the branch onto its upstream |
| **Sync** | Bring the branch up to date with its base |
| **Rebase** | Rebase onto the base branch |
| **Push** / **Publish** | Push, or publish an unpublished branch |
| **Force push** | Push with force-with-lease |
| **Reset** | Discard local state back to a known point |
| **Clear lock** | Remove the selected worktree's stale Git `index.lock` file |
| **Stash all** | Stash tracked and untracked changes |
| **Stage all** / **Unstage all** | Bulk staging |
| **Commit** | Stage changes and create a commit — see [Committing changes](#committing-changes) |
| **Change branch** | Switch this worktree to a different branch |
| **Change branch to ``** | Switch straight to the repository default branch in one step |
**Pull** fetches the branch's remote and fast-forwards onto it, and is offered only while the branch is behind its upstream. A branch that has diverged cannot fast-forward: **Sync** or **Rebase** are the ways through.
**Force push**, **Reset**, **Clear lock**, **Stash all**, and **Stage all** / **Unstage all** live behind **More** at the end of the action row. **Force push**, **Reset**, and **Clear lock** ask for a second click to confirm before they run.
Use **Clear lock** when Git reports that it cannot create `.git/index.lock` because the file already exists. Stop any Git process using the worktree first. The action removes only the selected worktree's index lock and succeeds if the stale file is already gone.
In the iOS app, open **Worktree Actions → Changes → Clear Lock**. Confirm the safety warning to run the same operation.
Do not clear the lock while a Git command is still running. Removing an active lock can allow concurrent writes to the Git index and corrupt it.
**Change branch to ``** names the repository default branch — for most repositories that reads **Change branch to main** — and skips the branch form entirely. It is hidden when another worktree already holds that branch, since Git refuses to check a branch out twice, and disabled when this worktree is already on it.
When Git cannot switch because of local changes, the action offers **Stash and retry**: it stashes tracked and untracked changes, retries, and leaves the stash for you to restore by hand. The one-step default-branch item has no retry of its own — it reports the error, and **Change branch** is where you stash and retry.
Git and worktree actions wait while a command or workflow terminal step configured to block Git is running on the same codebase. Commands that leave Git blocking off can run alongside these actions.
**New session** and **New plan** open the [new run page](/ai/run-new) with this worktree already selected, and its Jira ticket filled in when it has one.
A rebase that stops on conflicts leaves the worktree in **Rebase paused**. Resolve them by running a merge-conflict quick-action workflow, or **Cancel rebase** to restore the branch to its pre-rebase state.
A preparation conflict is detected before Sync or Rebase modifies the worktree. The dialog lists the managed paths and offers a force action only for this result. Forcing clears managed paths and assume-unchanged flags, discards edits on assume-only paths, runs Git, and reapplies preparations. A genuine Git conflict suspends preparations until the rebase is cancelled or completed.
**Open in VS Code** and **Open in VS Code Insiders** launch the worktree folder on its agent. They sit in the **Customize worktree** menu, alongside the worktree's tags and highlight color.
**Start Build** picks one saved configuration and a destination. The selected configuration names its source path, scheme, build configuration, and the agent the build will run on — the one that owns the codebase — so you can tell where the work is going before you start it.
The **Latest build** badge is a menu: **View build** opens the [build details](/builds/build-detail), and **Rebuild** starts a fresh build from the same configuration. A successful build that produced a runnable app also gets its run controls on the same row.
Select the card surface or **Open details** in the table to open the [worktree details page](/worktrees/worktree-detail). **View codebase**, **View repository**, and **Open in GitHub/GitLab** jump to the related resource, and **Refresh request** re-reads the pull or merge request state.
Workflow and command quick actions share one row when space allows, separated by a divider. They wrap into separate rows on narrower cards.
An active command adds a spinner menu beside its button. Open it to **Terminate**, **Restart**, or **View** each active run. The command button remains available, so you can start another run; its concurrency setting decides whether it starts or queues.
## Committing changes
**Commit** stages work and records it as a Git commit on the agent that owns the checkout, without opening a terminal.
The commit message is required. The dialog opens with the worktree's current changes already read from the agent.
**Signed commit** starts pre-set to whatever `commit.gpgsign` resolves to in that worktree's effective Git configuration, so the default matches what committing by hand would do. Clear it to commit unsigned, or set it to sign a commit that would not otherwise be signed.
**Stage all** is on by default and stages every tracked and untracked change. Turn it off to get a checklist of the current changes, pre-selected to whatever is already staged, and pick an exact set.
The agent stages, commits, and reports the new commit back. The page reloads the worktree when the job finishes.
A partial commit rebuilds the index from your selection. Anything you had staged but did not tick is left uncommitted and unstaged rather than being carried along.
The action is unavailable when the worktree has no staged or unstaged changes, has another operation running, is paused mid-rebase, or lives on an agent too old to support it. A commit that ends up with nothing staged fails with **No staged changes to commit** rather than creating an empty commit.
The same operation is available to automation: the **Commit worktree changes** workflow step and the `commit_worktree` MCP tool take the same message, signing, stage-all, and path options. Omitting the signing option there follows the worktree's Git configuration.
## Auto Sync
**Auto Sync** keeps a branch current without you asking: whenever its target branch changes, the worktree is rebased and pushed with force-with-lease.
It can also handle conflicts for you — enable **Run a quick-action workflow to resolve merge conflicts automatically** and select a merge-conflict workflow, optionally with a specific trigger choice. Auto Sync can be paused, resumed, and cancelled.
Auto Sync never forces through a preparation conflict automatically. It pauses with a preparation reason and shows the affected paths. **Force Sync** runs the existing conflict workflow when needed, reapplies repository preparations, and resumes Auto Sync after success.
## Auto Merge
**Auto Merge** hands the merge to the worktree's provider: the GitHub pull request or GitLab merge request merges as soon as its required checks, reviews, and branch rules are satisfied. Two optional follow-ups:
* **Delete this worktree after the pull request merges**.
* **Move the linked Jira ticket to the project's configured done status**.
Like Auto Sync, it can be paused, resumed, and cancelled, and reports **Auto Merge complete** when it lands.
## Moving a worktree to another agent
Moving pushes the branch from the source agent and checks it out on the destination.
Choose the destination agent and checkout, then either create a new worktree there or target an existing one. A destination with uncommitted changes is flagged — Git will carry them onto the incoming branch where it can.
**Delete old worktree after moving** cleans up the source. Primary worktrees cannot be deleted, so the option is unavailable for them.
The move reports its stage: pushing the source branch, checking out the destination, waiting for a stash decision, removing the old worktree, then complete.
If destination changes block the branch switch, choose **Stash and continue** — the destination's tracked and untracked changes are stashed, the move continues, and the stash is left for manual restoration. **Cancel move** stops it; the source branch stays pushed and the source worktree is kept.
A move is refused up front when the source agent is offline or too old, another operation is active for the repository, HEAD is detached, the source is dirty, the branch is behind or diverged from origin, or no compatible destination exists. The page names the specific reason.
## Deleting a worktree
**Delete worktree** permanently removes the folder and its local branch, optionally deleting `origin/` too. The repository default branch is protected from remote deletion.
All staged, unstaged, and untracked changes in the worktree are permanently lost. There is no stash-first option on delete.
## Hidden worktrees
A worktree that disappears from disk is not deleted immediately — it moves to **Hidden** and is retained for seven days. If the agent rediscovers it in that window, its saved metadata, tags, and highlight come back. **Purge** and **Purge all** remove hidden entries early.
## Related pages
Overview, working tree, branch changes, diffs, and coverage.
The repositories and checkouts worktrees are created from.