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

# Worktrees

> How each session gets its own branch and Git worktree, and how to create, switch, close, and delete them

A session is a branch with its own checkout of your repository. Git calls that checkout a
worktree. Because every session has its own folder, an agent can build and edit one task
without touching the files of another.

Your project's original folder is the **main** session. Every other session is a worktree
that FlowDeck creates for it.

## What a session owns

Each session has:

* One branch and one worktree folder.
* Its own chats and plans, agent settings, and drafts.
* Its own [Project Settings](https://docs.flowdeck.studio/macos/project-settings.md), including scheme, configuration, and
  launch arguments.
* Its own build output.

FlowDeck stores session worktrees outside your repository, in `~/.flowdeck/worktrees`. Your
original folder stays as you left it.

## Create a session

Press **⌘N**, choose **File → New Session**, or use the **+** button in the project header in
the sidebar. The New Session sheet has these fields:

* **Name** is what the session is called in the sidebar.
* **Base Branch** is the branch the new work starts from. It starts on the project's
  current branch.
* **Branch** appears only when automatic branch naming is off. Type the branch name. Your
  branch prefix, if you set one, is shown in front of the field.
* **Destination** appears when the project has a scheme FlowDeck can run. Choose an
  existing simulator, a new simulator with a device and OS version, or a Mac. The sheet
  remembers your last choice for the repository.

Choose **Create**. FlowDeck shows **Creating Session**, and **Creating Simulator** when it
makes a new one, and then opens the session. If you have **Ask Before Configuring New
Sessions** turned on for the project, a **Project Configuration** step follows. See
[Project Settings](https://docs.flowdeck.studio/macos/project-settings.md#how-new-sessions-pick-their-setup).

Creating a session reads the remote's branches but never pushes or creates a branch on the
remote.

### Branch names

With automatic naming on, FlowDeck builds the branch from your branch prefix and the session
name. For example, a prefix of `agent/` and the name "UI Improvements" gives
`agent/ui-improvements`. If that branch already exists, FlowDeck adds a number.

Change the prefix, or turn automatic naming off, in **Settings > Workflows > Git** under
**Automatic Branch Naming**. The default prefix is `agent/`.

If you type your own branch name, FlowDeck shows **Branch already exists** when the name is
taken. Names can use letters, numbers, dots, underscores, dashes, and slashes.

### Start from an existing branch

In the New Session sheet, click **Base Branch** to see a list of your local and remote
branches. Type in **Filter branches** to search. While FlowDeck fetches the remote, the sheet
shows **Updating remote branches…**. If FlowDeck finds nothing, the list says **No branches
found.**

Choose a branch to start the session on it. Use **Back** to return to the form. If you leave
the name empty, the session uses the branch's name.

A branch can be checked out in only one worktree at a time. If the branch you choose is
already in a worktree on this Mac, FlowDeck shows **Existing Worktree Found** and offers
**Create New Branch**. That returns you to the form with the branch as the **Base Branch**,
so the new session gets a fresh branch that starts from it.

### Start from another session's branch

Open the other session's menu and choose **New Session from Branch**. The New Session sheet
opens with that session's branch as the **Base Branch**. The new session gets its own new
branch that starts where the other one is, so you can run a related task separately.

## Switch between sessions

Select a session in the sidebar to switch its chat and project context. The sidebar shows a
status indicator for each session, and a pull request badge when the session's branch has a
pull request. For shortcuts and the Active Sessions view, see
[Projects & Sessions](https://docs.flowdeck.studio/macos/projects-and-sessions.md#move-between-work). To find a session by
name or branch, use [Open Quickly](https://docs.flowdeck.studio/macos/command-palette.md).

## The session menu

Hover over a session and choose the **⋯** button, or right-click the session.

| Item | What it does |
| - | - |
| **New Chat** | Starts a new chat in this session. |
| **Archived Chats** | Opens the session's chat history. |
| **Rename** | Changes the name shown in the sidebar. The branch keeps its name. Not available for the main session. |
| **Close** | Closes the session and keeps its worktree and conversation. Shown while the session is open. |
| **Delete** | Deletes the session. Not available for the main session. |
| **Worktree: branch** | A label that shows the session's branch. |
| **Copy Branch Name** | Copies the branch name. |
| **New Session from Branch** | Starts a new session from this session's branch. |
| **Open in GitHub** | Opens the branch on GitHub. Shown when the branch is pushed and the remote is on GitHub. |
| **Open PR #n on GitHub** | Opens the session's pull request. |
| **Open in…** | Opens the worktree folder in Finder, your editor, your terminal, or Xcode. |
| **Project Settings** | Opens [Project Settings](https://docs.flowdeck.studio/macos/project-settings.md) for this session. |

**Open in…** lists the editor and terminal you chose in **Settings → External Tools**. See
[Settings & External Tools](https://docs.flowdeck.studio/macos/settings.md). For projects generated by a tool such as
XcodeGen, the menu also has a submenu with **Open Project File** and **Generate Project**.

## Close a session

**Close** takes a session out of your active list without removing anything. Its worktree,
branch, and chats stay, and you can reopen it later from the sidebar.

If you close the session you are viewing, FlowDeck switches to the topmost open session. If
none is open, it switches to the main session.

## Delete a session

Choose **Delete** in the session menu. FlowDeck asks **Are you sure you want to delete the
session?** and explains that the session, its local branch, and any unpublished changes are
permanently deleted. Choose **Delete Session** to confirm.

If FlowDeck created a simulator for the session, the sheet also shows **Also delete the
simulator**, checked by default. Clear it to keep the simulator.

Deleting a session removes its worktree, its local branch, and its local conversation data.

> [!WARNING]
>
> Deleting can discard work that you have not pushed. Review the Changes tab and push
> anything you need first.

What deletion protects:

* The main session cannot be deleted.
* A remote branch is never deleted, and neither are commits you already pushed.
* If FlowDeck cannot confirm the worktree was removed, it keeps your conversation data and
  shows **Session Delete Failed**.
* If only the branch cannot be removed, the session is still deleted and FlowDeck shows
  **Branch Delete Failed**.

## Worktrees and Disk Cleanup

Worktrees take disk space, and [Disk Cleanup](https://docs.flowdeck.studio/macos/clean.md) can remove old ones. It lists a
worktree only when its branch is merged and its working copy is clean. It never selects
worktrees for you, and it skips any worktree that is open in FlowDeck or has a live agent
session, build, or test.

Disk Cleanup removes the worktree folder only, and the removal is permanent. The branch stays. To get the work back, create a
session and choose that branch as described in
[Start from an existing branch](#start-from-an-existing-branch).


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