Worktrees

Run a chat in an isolated git worktree of your project. Each worktree is a separate branch with its own checkout under .bricks/worktrees/, so the agent can build and experiment on a branch without touching your main checkout or any other chat. Merge the work back when you’re happy with it.

​

Pick a working tree

A worktree pill — a branch icon and the current target name — appears in a project chat’s input bar, alongside the other selectors. It shows the working tree the chat runs in, Main by default. You can change the target only while the chat is empty. Once the chat has messages, the working tree is locked: the pill stays visible but no longer opens (its tooltip reads Working tree for this chat (locked once it’s started)). Click the pill to choose between:

• Main — your project’s primary checkout
• An existing worktree, listed under the Worktrees heading
• New worktree… — create a fresh one

​

Create a worktree

Choose New worktree… to open the New Worktree dialog.

• Enter an optional Name. As you type, a live preview shows the branch and folder it resolves to: .bricks/worktrees/<name>. The name is slugified — lowercased, with spaces and other characters collapsed to -, capped at 60 characters.
• Leave the name blank to get a generated one such as brave-otter.
• Click Create. CTOR creates the branch and an isolated checkout from your project’s default branch, then runs bun install in it. The chat switches to the new worktree automatically.

If creation fails, the partial worktree is rolled back so a retry starts clean. The first worktree you create adds .bricks/worktrees/ to your project’s .gitignore and commits that change, so checked-out worktrees are never committed back into the project.

​

Work in a worktree

A worktree chat shows a branch icon next to its entry in the sidebar. The agent — and everything the chat does — runs against the worktree’s branch and files, isolated from your main checkout. Because a worktree is meant to be integrated through Merge to main, the publish actions in the chat header’s actions menu are limited: Push Config and Deploy are default-branch operations — merge your work back first, then publish from the main chat.

​

Merge to main

Open the Worktree dropdown in the chat header and choose Merge to main. CTOR:

1. Commits the worktree’s pending changes as a snapshot commit.
2. Merges the worktree’s branch into the default branch in your main checkout.

The main checkout must be on the default branch with no uncommitted changes. Otherwise the merge stops and tells you what to fix first (for example, commit or stash the main checkout’s changes). If the merge hits conflicts, it is aborted automatically and the dialog lists the conflicting files. Resolve them manually, then run Merge to main again.

​

Remove a worktree

Open the Worktree dropdown and choose Remove worktree. This deletes the worktree’s directory but keeps its git branch. If the worktree has uncommitted changes, the first attempt is blocked with a warning. Confirm again with Discard changes & remove to force the removal and lose those changes.

​

Orphaned worktrees

If a worktree’s directory is removed — from another window, or outside CTOR — the chat detects that its checkout no longer exists and turns read-only, showing the banner This worktree no longer exists on disk — the chat is read-only. The conversation stays readable; switch to another chat to keep working.