Branching, merging, promoting

Three ways to turn part of a conversation into a conversation of its own. None of them touch the transcript they read.

Branch

Put the cursor on a turn in the spine and press b, or:

braids branch --lane 46360382 --at 491
braids branch --lane 46360382 --at 491 --name "try option c"
braids branch --lane 46360382 --at 491 --workspace

braids writes a new transcript holding that turn's ancestry from the root, and nothing after it, then gives you the claude --resume command for it. The source file is opened read only. A test hashes it before and after to prove it.

Records are copied as they were, including the environment they captured: the working directory, the git branch, the file snapshots. A branch resumes believing in the world as it was when that turn happened, which is deliberate. The harness already refuses an edit built on a stale read, and that is the only point where the difference can do harm.

A workspace of its own

--workspace gives the branch a git worktree, so two branches can edit the same file without seeing each other. braids refuses rather than half-doing it when a worktree cannot exist: the conversation's directory is not a git repository, or the branch name is taken.

Merge

braids merge --lane 46360382 --from a1b2c3d4 --plan   # what would come over
braids merge --lane 46360382 --from a1b2c3d4

This writes a third conversation: the base in full, then the turns that happened on the branch. It is a splice of real messages, not a summary of them. Neither original is touched.

The new records get fresh IDs, because two conversations sharing a message ID is exactly what braids reads as a fork, and reusing them would leave a lane that looks like a branch of the thing it was merged from. braids refuses when one side already contains the other, rather than producing a duplicate under a new name. --plan reports the turn counts and stops.

Promote a subagent

braids agents --lane 46360382
braids promote --lane 46360382 --agent 9f2a1c

A subagent already holds a complete, linear exchange. It is only marked as a sidechain and filed under its parent. Clearing that mark and giving it a session ID of its own is enough for the harness to resume it, so an exchange that was visible as a single tool call becomes a conversation you can read, search and branch like any other. Its own transcript is left alone.

Carrying on in a terminal

y copies the resume command for the row under the cursor. o opens it. braids drives tmux and iTerm2 directly. Anywhere else, set a template:

export BRAIDS_SPAWN='tmux new-window -c {dir} -n {name} {cmd}'

{cmd}, {name} and {dir} are filled in. Every value is shell quoted when it is substituted, so do not put quotes around a placeholder yourself. That quoting is not cosmetic: a conversation titled with a backtick used to reach sh -c unquoted.