Skip to main content
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, 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. 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. To find a session by name or branch, use Open Quickly.

The session menu

Hover over a session and choose the ⋯ button, or right-click the session. Open in… lists the editor and terminal you chose in Settings → External Tools. See Settings & External Tools. 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.
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 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.