Worktrees

Braide uses git worktrees to give each session an isolated copy of the project's repository. This page explains what worktrees are, how they interact with the project, and how to manage changes made by agents.

Worktrees are the default mode for a session. Braide also supports two other modes — project-root (runs in the repo root, no worktree) and scratch (runs in an empty ephemeral directory). See Session Modes for an overview of all three.

What is a Worktree?

A git worktree is a linked working copy of a repository that shares the same .git data but has its own checked-out branch and file state. Git natively supports multiple worktrees from a single repository.

When you create a session, Braide runs:

git worktree add <worktree-path> -b acp-session/<session-id>

This creates a new branch from the project's current HEAD and checks it out in a directory specific to the session:

~/.braide/projects/<project-id>/sessions/<session-id>/worktree/

How Worktrees Provide Isolation

  • Each session operates in its own worktree directory with its own branch.
  • Agents read and write files only within the session's worktree — they cannot affect other sessions or your main working directory.
  • The embedded terminal for each session also starts in the session's worktree, so any commands you run there operate on the same isolated copy.
  • Multiple sessions can run in parallel without conflicting, even if they modify the same files.

Working with Session Branches

Branch Naming Convention

Session branches follow the pattern acp-session/<session-id>-<session-title>, where the session title is sanitized for git compatibility (lowercased, non-alphanumeric characters replaced with hyphens, truncated to 60 characters). When a session is first created it has no title, so the branch starts as acp-session/<session-id>. The branch is automatically renamed whenever the session title is set or changed — whether from the first prompt, an attached GitHub issue, or a manual rename.

Viewing Changes

From the session's terminal (or any terminal pointed at the worktree path), you can inspect what the agent has changed:

# See which files changed
git status

# View the full diff
git diff HEAD

Braide also displays a diff summary in the session UI.

Committing Changes

If you're happy with the agent's changes, commit them from the session's terminal:

git add -A
git commit -m "feat: implement feature X"

The commit is made on the session's branch (acp-session/<session-id>-<session-title>).

Rebasing from the Base Branch

If the project's main branch has moved forward since the session was created, you may want to rebase the session branch to incorporate those changes:

# Fetch latest changes (if working with a remote)
git fetch origin

# Rebase onto the main branch
git rebase main

If there are conflicts, resolve them as you normally would with git, then continue:

git rebase --continue

Merging Back to the Main Branch

Once the session's work is complete and committed, you can merge it back into the main branch. From your project root (not the worktree):

# Switch to main
git checkout main

# Merge the session branch
git merge acp-session/<session-id>-<session-title>

Alternatively, push the session branch and open a pull request if your workflow uses code review.

Tip: Creating a project-root session gives you an agent that already runs in the project root, so you can drive merges and rebases through it without leaving Braide.

Pushing the Session Branch

You can push the session branch to a remote for review or backup:

git push -u origin acp-session/<session-id>-<session-title>

Session Deletion and Cleanup

When a session is deleted, Braide:

  1. Removes the worktree — The worktree directory is deleted and unlinked from the repository.
  2. Renames the branch — The session branch is renamed from acp-session/<session-id>-<session-title> to acp-session-deleted/<session-id>-<session-title>, preserving the commit history rather than deleting it.

If you need to recover work from a deleted session, the commits are still available on the renamed branch:

git log acp-session-deleted/<session-id>-<session-title>

Relationship to the Project Root

The project root is the original directory you selected when creating the project. It is the main repository. Worktrees are separate working directories that share the same git history and object store, but each has its own branch and file state. Changes in a worktree do not appear in the project root (or any other worktree) until they are committed and merged.

Projects Without a Git Repository

Worktrees require a git repository at the project root. When you add a project whose root is a plain directory (no .git), Braide cannot run git worktree add, so worktree mode is not available.

What happens when you click "New Session" on a non-git project:

  1. createWorktree detects that the root is not a git repo (via git rev-parse --is-inside-work-tree) and returns null instead of creating a worktree.
  2. The session is auto-promoted to project-root mode — the agent runs directly in the project root, the session is badged with the orange ROOT pill, and baseBranch is not persisted.
  3. The agent's CWD is the project root itself, so any files it writes land there.

The auto-promotion happens transparently — you do not need to choose a mode from the split button's menu.

What UI is suppressed on a non-git project:

  • The branch selector in the prompt toolbar is hidden (there are no branches to pick).
  • The branch list endpoint (GET /api/projects/<id>/branches) returns { "error": "Not a git repository" } with a 400 status; the UI degrades gracefully.
  • The merge, commit, and pull-request sidebar actions are disabled because there is no session branch with commits ahead of a base branch.
  • The diff panel remains empty because there is no git index to diff against.
  • Session branch rename / archive are treated as no-ops — when you set a session label or archive a session, Braide checks for a git repo first and skips the git branch -m call entirely, rather than letting it fail and log a spurious error.

Migrating from non-git to git: If you later run git init in the project root and create a new session, that new session will use worktree mode normally. Existing sessions created before the git init retain their project-root mode on disk (the mode is chosen at creation time and does not migrate).