The Backbencher guide.

Both installers prefer npm and install the same package. Only when npm is unavailable do they fall back to a release binary from the backbencher-hq/backbencher-brain GitHub releases, and only after its sha256 checksum verifies against the release’s checksums.txt. Pin with VERSION=0.1.0 in front of either command ($env:VERSION="0.1.0" on Windows).

Pin the npm package with npm install -g @backbencher/brain@0.1.0.

Verify

bb --version

If bb is not found, check that your npm global prefix (npm prefix -g) or ~/.local/bin is on your PATH, then run the absolute path to verify.

1 · Built-in directory skips

Always on, in every project, before any of your own rules are read. These directories never reach the parser:

2 · Your gitignore rules are respected

Anything git ignores, the indexer skips — a .gitignore at any level of the tree is read as it walks, so a project that is already gitignored correctly needs no extra configuration.

3 · Your .bbignore overrides all of it

A project-local .bbignore file (gitignore syntax) has higher priority than .gitignore — use it when you want git to track something but the indexer to skip it, like large generated fixtures. After you add it, bb index --changed applies it. If an unexpected directory shows up in your index, that is the fix — and it is a bug worth reporting.

Size tiers — a guardrail, not a silent cap

One generated blob can stall a whole run, so very large files are handled by tier instead of being parsed blindly:

How long indexing takes

The first index is the expensive pass: it parses every discovered file and then runs the derived phases. A re-run of an unchanged project is fast, because files whose size and modification time are unchanged are not re-parsed at all. Progress streams while it runs, and bb status reports per-phase timings of the last run.

1 · Reads refresh stale files inside a budget

When a read path touches files that are stale or missing in the index, it repairs exactly those files within a budget before answering, and says so in an auto-refreshed N files in Xms line. The budget is 25 files or 2 MiB of changed bytes, whichever comes first, and it is tunable through the environment:

BB_NO_AUTO_REFRESH=1 opts out entirely. If the repair would exceed the budget, or another index run holds the lock, the tool answers from existing data with a staleness footer instead of pretending the index is current.

2 · Incremental, on purpose

What a changed file recomputes

Only what the changed files touch — never the whole index. This is the exact list, phase by phase:

Two honest edges: embeddings are asynchronous, so semantic search can lag symbol and relationship freshness by a few seconds after an edit; and a derived phase that fails leaves the run’s status partial rather than silently claiming success. A run summary reports what it did as derivedPass: full | bounded | deferred | skipped-unchanged — a bounded pass covers the touched files, a full pass covers everything, and a deferred pass means the derived data is still owed (run bb index --post).

Diagnose a broken setup or inconsistent index:

bb doctor

bb doctor is read-only. bb doctor --fix repairs file-permission problems only (0600 on the config); it changes nothing else. The first bb index run also offers the setup wizard interactively — skip it once with bb index --no-setup.

From the terminal, run any tool with JSON arguments:

bb tool bb_search --args '{"mode":"symbol","query":"createSession"}'

Global flags, accepted by every command: -v, --version · --verbose · --quiet.

Daily diagnostics:

bb stats          # counts
bb status         # is an index running? what did the last run do?
bb health         # is the index healthy and fresh?
bb doctor         # is the embedding setup consistent?

Where the index lives

One directory, keyed per project, outside your repository and outside the installed program:

~/.bb/projects/<project-id>/brain.db

The index: symbols, relationships, embeddings.

~/.bb/wasm

The parser cache.

The <project-id> is a sha1 of the project's absolute path, so two checkouts of the same repository at different paths have separate indexes. Override the whole location with BB_DATA_DIR — recommended where the home directory is not reliably writable or persistent (sandboxes, CI, editor hosts).

Upgrading keeps your data

New releases run idempotent schema migrations when they open the database: an upgraded bb either uses the existing index as it is or upgrades it in place — it never wipes it. To move to a new release, run npm install -g @backbencher/brain@latest (or re-run the installer, which does the same thing through npm); npm install -g @backbencher/brain@0.1.0 pins a specific release. There is no separate in-place upgrade subcommand.

Uninstall and reinstall

Uninstalling removes the program, not ~/.bb. Reinstall and every index, embedding and history entry is exactly where you left it. You start from zero only if the project moved to a different absolute path — then:

bb index --import /path/to/old-brain.db

adopts (re-homes) an existing index for the project at its current location. Moving a database between machines works the same way when the codebase fingerprint matches.

See and reclaim disk space

bb projects                  # every indexed project: DB path, size, counts, last index
bb projects --sort size      # biggest indexes first
bb projects --remove <id>    # delete one project's index + embeddings
bb stats                     # committed counts for the current project

Removing a project is the only operation that deletes an index. Nothing else in the CLI does, and no command sends your code or your index anywhere.

Still stuck? Send the output of bb health and bb stats to support.