A project in Braide is a named reference to a directory on your local filesystem. Projects are the top-level organizational unit — all sessions belong to a project.
What Projects Do
Group sessions — Each project has its own list of sessions, keeping conversations organized by context
Set working directory — When agents run commands or access files, they operate within the project's directory
Store preferences — Per-project settings (personas, actions, language servers, archive retention) are scoped to the project
Enable GitHub integration — If the project directory is a Git repository with a GitHub remote, you can browse and attach issues and pull requests
Start a project
Creating a Project
Click the + button at the end of the project tab bar in the navbar. You'll be prompted to:
Pick a directory — Browse your filesystem to select the project root
Name the project — Give it a descriptive name (this can be changed later)
The project is created and immediately selected as the active project.
Managing Projects
Each project appears as a tab in the navigation bar. You can:
Switch between projects by clicking on their tab
Rename a project by double-clicking on the tab name
Close or delete a project by clicking the close (×) button that appears when hovering over a tab — see Closing vs Deleting below
Reorder projects by dragging and dropping tabs to rearrange them — the order is persisted across sessions
Closing vs Deleting
Clicking the × on a project tab opens a confirmation modal with two distinct actions:
Close (default) — removes the tab from the navigation bar but keeps the project's sessions, worktrees, branches, schedules, and preferences intact on disk. The project is archived: hidden from the project list, but ready to be reopened later.
Delete — permanently removes the project's data from your Braide home directory. Sessions, worktrees, archived branches, schedules, and project preferences are all destroyed. This cannot be undone.
Neither action ever touches the project's source directory.
Reopening a Closed Project
When you click + to add a project and select a directory that already has Braide data — whether that project is currently open or has been closed — Braide detects the existing data and asks you to choose:
Reuse (default) — reopens the existing project. If it was closed, it is unarchived and selected. All previous sessions, worktrees, and settings are preserved.
Start fresh — permanently deletes the existing project data and creates a new project at the same directory. This cannot be undone.
Matching is performed on the exact directory path of the project root. Projects whose source directory has been moved or renamed on disk are not detected automatically.
Project Storage
Project data (sessions, metadata) is stored in your Braide home directory — by default ~/.braide/ — separate from the project's source directory. Closing a project keeps this data on disk and marks the project as archived in its settings.json; deleting a project removes the data; neither action touches the original source directory. See the Configuration reference for details on the home directory layout and how to override it.