Projects & 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 (⌘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.

​

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 (⌘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.

​

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