> ## 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.

# Projects & Sessions

> Add projects, isolate work in Git worktrees, and move between active sessions

FlowDeck can keep several repositories open in one workspace. Within a repository,
each session has its own branch and Git worktree, so an agent can build and edit one
task without touching another task's files.

## Add a project

Choose **File → Add Project…** (or press **⌘O**) and choose one of three entry points:

* **New App** creates a new Apple project, with platform and location choices before
  it opens in FlowDeck.
* **Local folder** opens an existing `.xcodeproj`, `.xcworkspace`, or folder.
* **GitHub** lets you browse or search accessible repositories, clone one, and open it
  in the workspace.

When a project needs configuration, FlowDeck guides you through selecting the
workspace, scheme, destination, and build configuration. Those choices are saved per
worktree, so a different task can use a different scheme or target without overwriting
the first one.

## Create a session

Press **⌘N** or choose **File → New Session**. You can start a fresh branch and
worktree, open an existing local or remote branch, or create a session from another
session's branch.

Each session keeps its own chat history, Code or Plan mode, agent settings, drafts,
project configuration, and DerivedData. Give a session a descriptive name to make its
task easy to recognize in the sidebar.

## Move between work

The sidebar lists sessions and worktrees for the active repository. Select one to
switch its chat and project context. With more than one project open, **⌘0** opens
Active Sessions and **⌘1** through **⌘9** switch directly between projects.

Use [Open Quickly](/macos/command-palette) (**⌘K**) when you want to search projects,
sessions, branches, and actions from one place.

## Close or delete a session

Closing a session preserves its conversation and worktree so you can return later.
Deleting a session asks for confirmation and removes its worktree, local branch, local
conversation data, attachments, and per-worktree build data. FlowDeck protects the
main worktree, and deleting a session never deletes its remote branch.

<Warning>
  Deleting a session can discard unpublished local work. Review the Changes tab and push
  anything you need before confirming deletion.
</Warning>

## Generated projects

For projects managed by **XcodeGen** or **Tuist**, FlowDeck detects the manifest and
offers to generate the Xcode project before you build. You can run **Regenerate
Project** later from Open Quickly.

## Try it safely

The [sample project](/macos/sample-project) is a local-only project with prepared
sessions and a configured simulator. It is a good place to explore branches,
worktrees, and the agent before opening a production repository.