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

If you choose a folder that is not an Apple project, FlowDeck explains that Apple
development tools will be unavailable and lets you cancel or continue. If it is not
a Git repository, choose whether to cancel, open it without Git features, or create
a local repository. You can initialize Git later from the Changes tab.

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.

## Configure a session

Open a session's **Project Settings** from its menu or [Open Quickly](https://docs.flowdeck.studio/macos/command-palette.md)
(**⌘K**) to review its build setup. The window includes:

* **Build Settings** for the workspace, scheme, configuration, and destination.
* **Schemes** for the schemes FlowDeck discovers in the selected workspace.
* **Xcodebuild Settings** for additional project build settings.
* **Swift Packages** for direct remote or local package dependencies and their targets.

New sessions start from the repository's last valid build selection. Use the session
settings window when this task needs a different setup. For the global tools around a
project, see [Settings & External Tools](https://docs.flowdeck.studio/macos/settings.md).

## 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 and plan conversations, agent settings, drafts,
project configuration, and DerivedData. Give a session a descriptive name to make its
task easy to recognize in the sidebar. Start from a branch when you need to resume
parked work; start from another session's branch when you need a related isolated task.

Use the **+** menu above the conversation to create a **New Chat** or **New Plan**,
choose **Open Plan** from the plan library, or browse **Chat Archive** across all
projects and sessions. New tabs appear on the right, and **⌘T** creates a Chat tab.
Opening the archive keeps your current conversation selected. Overflow arrows let you scroll the tabs in either direction.

New conversations receive a title in the background after the first message is sent, using your configured utility model. You can rename a tab from its context menu while the agent is working; your chosen name always takes precedence. If title generation is unavailable, the current name stays in place.

## Archived chats

Hover over a tab and use its archive-box button, or press **⌘W**, to archive it.
Archiving selects the previous tab to the left, or the next tab when archiving the first. It preserves a newer selection you make while saving. Archiving from the button, tab menu, or keyboard asks for confirmation only if the agent is active. **Chat Archive** shows
one searchable list grouped by project and session, with the archive date and recorded
models. Search includes saved chat text, titles, models, providers, projects, and sessions;
use the chat-kind and project filters to narrow the list.

Restore a chat to its original tab, another existing session in the same project, or a
new session with your chosen base branch. Restoring to another session keeps its existing
chats and working files intact. Saved history can be restored even when its original
checkout is gone, as long as the repository is available.

The archive permanently keeps the newest **250 chats across all projects**. Older saved
chats and their owned attachments are removed; chats involved in restore or recovery are
protected until the operation finishes. You can also delete one archive or choose
**Delete all**. Delete all includes archives hidden by search and filters, shows the global
count for confirmation, and does not include chats archived afterward. Permanent deletion
cannot be undone and does not remove the provider’s original history.

## 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 **⌘1** through **⌘9** to select conversation tabs in the current session,
in their displayed order with Plan tabs first.

Use [Open Quickly](https://docs.flowdeck.studio/macos/command-palette.md) (**⌘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.

## Generated projects

For a project managed by **XcodeGen**, 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](https://docs.flowdeck.studio/macos/sample-project.md) 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.


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