Start here

braids reads the transcripts Claude Code already writes and draws them as a graph you can search, branch and prune. It never talks to a model.

What it is

Claude Code keeps one conversation per session, in one JSONL file under ~/.claude/projects. That works while a session stays on one thread. Real work does not: you fork to try something, double back, spawn three side quests, and a week later you have thirty session files with no shape between them.

braids gives them a shape. It does four things.

1. Draws the graph. Every conversation, with branches under the conversation they were cut from.
2. Searches all of it. Messages, tool calls, project memories, and the names of files a session left on disk.
3. Branches anywhere. Put the cursor on a turn, get a new conversation that starts there.
4. Shows the mess. Scratch files, memories the index has lost track of, subagents you never saw.

Install

# picks the build for your machine and checks it against the published sums
curl -fsSL https://braids.chat/install.sh | sh

# or with Go
go install github.com/Ashes47/braids/cmd/braids@latest

# or from source
git clone https://github.com/Ashes47/braids && cd braids
make install

The installer puts one binary in /usr/local/bin when that is writable, and ~/.local/bin otherwise. Set BRAIDS_BIN_DIR to choose, or BRAIDS_VERSION to pin a version.

Uninstalling

braids hooks --remove    # take the hook back out of ~/.claude/settings.json
rm "$(command -v braids)"
rm -rf ~/.braids         # the index and its sidecar files

Your conversations live in ~/.claude and are never touched, so removing braids costs you the map and nothing else.

Windows

There are Windows builds, as a zip on the releases page: unzip it and put braids.exe somewhere on your PATH. There is no one-line installer, because the one braids has is a POSIX shell script and it will not ship a PowerShell one it has never run.

Everything reads and searches the same. Two things are not offered rather than offered broken: o does not open a terminal through BRAIDS_SPAWN, because that template runs through a shell and quoting it for cmd.exe is a different set of rules that braids cannot test, and v does not update, because there is no installer to run. Both fall back to copying, which is what braids already does for any terminal it cannot drive. The tests run on Windows in CI.

Staying current

Run the same line again to update. It asks the binary it would replace what version it is and stops if there is nothing to do, and it replaces braids where it already lives, so a build installed with Go is not shadowed by a second copy in /usr/local/bin.

braids cannot tell you that a newer version exists, because finding out means asking and braids makes no network calls. It can say how long it has been since anyone checked, which it reads from two local facts: when this binary arrived, and when the installer last ran. After a month the map's version row grows · 3 months old · v to update, and v runs the installer, printing the command before it does. Checking and finding yourself current resets the clock, so it asks at most once a month and never claims you are behind.

The first index

braids index

This reads every transcript under ~/.claude/projects and writes one SQLite file to ~/.braids/index.db. On a corpus of 28 conversations and about 360 MB of transcripts it takes about eight seconds. Every run after that reads only what changed, which is single-digit milliseconds, and the map re-indexes on its own while it is open.

Nothing else creates the index. A read command pointed at a database that is not there says so rather than making an empty one and answering no matches, which is a wrong answer wearing the shape of a right one.

braids search anything --db /nope/absent.db
# braids: no index at /nope/absent.db (run: braids index)

Five minutes in

$ braids

Then, in order of how often you will want them:

Nothing here is a command you have to memorise. The header of every screen lists every key that screen takes, and the glyph key next to it names every mark on the screen.

Everything else

Nine more pages, in the order they make sense in.

Where things live