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.

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

Deleting a Project

To delete a project:

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

Deleting a project removes the project reference and all its session data from Braide. It does not delete the source directory or any files in it.