Reference

Every command, every flag, every environment variable.

Commands

Command	What it does
braids	open the map
braids index	index new and changed transcripts
braids search QUERY	search conversations, memories and work-product names
braids lanes	list indexed conversations
braids branch	cut a new conversation at a turn
braids merge	bring a branch back, as a new conversation
braids promote	turn a subagent into its own conversation
braids agents	list the subagents a conversation spawned
braids work	browse what a session wrote to disk
braids memories	what a project remembers, and what it has lost
braids explain FILE	which conversations were live when this file last changed
braids show --lane ID	read the turns of a conversation, around one turn
braids doctor	every health check braids can run on itself, in one place
braids status	how many conversations are owed a reply, in one line
braids brief	the state of play in the project you are standing in
braids hooks	install, remove or inspect the hook
braids skill	install, remove or inspect the Claude Code skill
braids version	the version, the commit, and how old this build is
braids help	everything, briefly

Flags, by command

Common

Flag	What it does
--db PATH	index location. Default `$BRAIDS_DB` or `~/.braids/index.db`
--json	machine readable output, with whole IDs
--help	the flags that command takes

braids (the map)

Flag	What it does
--ascii	narrow glyphs, for terminals that draw box characters double width
--print	render one frame to stdout instead of opening the map
--lane ID	with --print, that conversation's spine
--query Q	with --print, the search screen for a query
--width N	frame width when printing, default 92
--height N	frame height when printing, default 24

braids index

Flag	What it does
--root DIR	transcript root. Default `~/.claude/projects`
--full	re-read every transcript instead of only what changed

braids search

Flag	What it does
--lane ID	restrict to one conversation
--project NAME	restrict to one project
--since WHEN	a date or an age: 2026-08-01, 30d, 6w, 12h
--until WHEN	the same, as an upper bound
--type LIST	conversation, memory, artifact
--kind LIST	text, thinking, tool_use, tool_result
--limit N	maximum hits, default 20

braids status

Flag	What it does
--within D	only conversations touched this recently, default 24h, 0 for all
--always	print a line even when nothing is waiting

It is built for Claude Code's statusLine, so it prints nothing when nothing is waiting and never fails: no index is not an error, it is nothing to say. Add it to ~/.claude/settings.json:

{ "statusLine": { "type": "command", "command": "braids status" } }

The window is the difference between a number worth glancing at and one that never changes. The map counts a conversation abandoned three weeks ago mid-thought, and is right to, because it is still an open loop. On a status line that same number never moves.

braids show

Flag	What it does
--lane ID	conversation to read
--at TURN	centre the window on this turn
--around N	turns either side of --at, default 6
--from N	first turn, instead of --at
--to N	last turn
--kind LIST	text, thinking, tool_use, tool_result
--chars N	characters of each block, default 600, 0 for all
--plain	strip the terminal colour codes recorded in tool output

braids branch

Flag	What it does
--lane ID	conversation to branch from
--at TURN	turn number to branch at
--name NAME	name for the new conversation
--workspace	give the branch a git worktree of its own

braids merge

Flag	What it does
--lane ID	conversation to carry on from
--from ID	branch whose turns are brought over
--name NAME	name for the merged conversation
--plan	report what would come over, including how many of the branch's turns failed, and stop

braids explain

Flag	What it does
--limit N	how many commits to look back over, default 5
--window D	how long before a commit a turn still counts, default 3h

braids promote, agents, work, memories, hooks

Flag	What it does
--lane ID	promote, agents, work: the conversation
--agent ID	promote: the subagent to promote
--path SUB	work: directory within them to list
--orphans	work: sets whose conversation is gone
--reclaim	work: with --orphans, move them to the bin
--project NAME	memories: only this project
--root DIR	memories: transcript root
--install	hooks and skill: put it in place
--show	skill: print it instead of installing it
--dir DIR	skill: skills directory, default `~/.claude/skills`
--remove	hooks: stop asking
--settings PATH	hooks: settings file, default `~/.claude/settings.json`

Environment

Variable	What it does
BRAIDS_DB	where the index lives
BRAIDS_ASCII	set to anything to make `--ascii` the default
BRAIDS_SPAWN	command template for `o`, understanding `{{cmd}} {{name}} {{dir}}`
BRAIDS_VERSION	installer only: pin a version
BRAIDS_BIN_DIR	installer only: where the binary lands

When something is wrong

What you see	What it means
no index at PATH (run: braids index)	nothing has indexed yet, or --db points somewhere else. Reads never create one
no conversations indexed yet	the index exists but is empty. Run `braids index`
the box characters are double width	run with `--ascii`, or set `BRAIDS_ASCII`
Hooks: not installed	waiting states fall back to what the transcript can prove. `braids hooks --install`
hook reads an event on stdin	you typed `braids hook`. You wanted `braids hooks`
the index was written by another version of braids	you have upgraded. Run `braids index` once, or just open the map, which re-reads by itself. Nothing is lost either way
N conversations grew and produced no new messages	braids could read them before and cannot now, which is what a format change looks like while it happens. `braids index` names them
N conversations hold bytes braids could not read	a transcript yielded no messages at all, which usually means the format changed. `braids index` names the files. Please report it
a work product is refused	it is the harness's own record of the job, and deleting it would confuse the writer