Creating a Project

Projects connect Braide to directories on your filesystem. Here's how to set one up.

Creating a New Project

  1. Click the + button at the end of the project tab bar in the top navigation
  2. A directory picker modal appears — browse to the directory you want to use
  3. Enter a project name in the text field
  4. Click Create

The project is created and automatically selected as your active project. A new tab appears in the tab bar, and the left sidebar will show an empty session list for this project.

Reusing an Existing Project

If you select a directory that Braide has previously been pointed at — including projects you've closed — Braide detects the existing data and offers a second modal before creating anything new:

  • Reuse (default, highlighted) — reopens the existing project with all its sessions, worktrees, schedules, and preferences intact. If the project was closed, it is unarchived. The name you typed in the picker is not applied; the existing project keeps its original name. (You can rename it afterwards by double-clicking the tab.)
  • Start fresh — permanently deletes the existing project data, then creates a brand-new project at the same directory using the name you typed. The previous sessions, worktrees, and preferences are gone for good.
  • Cancel — abandons the add-project flow and keeps the existing project untouched.

Matching is performed on the exact directory path only. If the directory has been moved or renamed on disk since the project was last opened, Braide will not detect it, and a fresh project will be created.

Choosing a Directory

The directory you select becomes the working directory for all agent sessions in this project. Consider choosing:

  • The root of a code repository for software development work
  • A specific subdirectory if you want to focus the agent on a particular area
  • A Git repository if you want to use GitHub integration features

Directories That Aren't Git Repositories

Braide works best when the project root is a git repository — it can create isolated worktree sessions, show per-session diffs, and drive the commit / merge / pull-request actions. If you point the project at a plain directory, the session sidebar adapts:

  • The New Session button's primary action becomes New Session in Project Root so clicks always produce a working session, never a silent fallback.
  • A banner with an Initialise Git Repository button appears beneath the button. Clicking it runs git init, stages any existing files with git add -A, and makes an initial commit so worktree sessions become available immediately. See Projects Without a Git Repository for the exact commands and what they mean for your working tree.

After Creation

Once your project is created, you can:

  • Create sessions to start working with agents
  • Configure personas, actions, and language servers in Settings > Project Settings
  • Browse GitHub issues and pull requests if the directory is a Git repo with a GitHub remote

Renaming a Project

To rename a project:

  1. Double-click on the project tab name
  2. Type the new name
  3. Press Enter or click away to save, or press Escape to cancel

Reordering Projects

To reorder project tabs:

  1. Click and hold on a project tab
  2. Drag it left or right to the desired position — other tabs will slide out of the way
  3. Release to drop the tab in its new position

The tab order is automatically saved and persisted across sessions.

Closing or Deleting a Project

Clicking the × on a project tab opens a confirmation modal with three actions: Close, Delete, and Cancel. They are deliberately distinct because closing is non-destructive and reversible, while deleting is permanent.

To open the modal:

  1. Hover over the project tab to reveal the close (×) button
  2. Click the × button

Close (default)

Close is the highlighted, primary button. Pressing Enter while the modal is focused triggers it. Closing a project:

  • Removes the tab from the navbar
  • Marks the project as archived in its settings.json so it no longer appears in the project list
  • Preserves every session, worktree, archived session branch, schedule, image upload, and project preference on disk

To reopen the project later, click + in the tab bar and select the same directory; Braide will detect the closed project and offer to reuse it (see Reusing an Existing Project above).

Delete

Delete is the destructive action — distinguished visually from Close by its danger styling. Deleting a project:

  • Removes the tab from the navbar
  • Permanently removes the project's data directory under your Braide home (~/.braide/projects/<id>/), including all sessions, worktrees, archived branches, schedules, and preferences
  • Cannot be undone

Neither Close nor Delete touches the source directory the project pointed at — Braide only ever manages its own metadata under the home directory. Files in the project root, including any git worktrees that had already been removed back into the main repository, are unaffected.

Cancel

Cancel, clicking outside the modal, or pressing Escape dismisses the modal with no changes.