Docs — the Backbencher guide

Installation

Backbencher runs fully local: the bb CLI, the SQLite index, and the analysis all live on your machine. Your source code never leaves it.

macOS and Linux

curl -fsSL https://backbencher.cc/install.sh | bash

Windows PowerShell

irm https://backbencher.cc/install.ps1 | iex

Verify

bb --version

If bb is not found, run ~/.local/bin/bb --version and add ~/.local/bin to your PATH.

First index

Build the index for a project, then inspect it:

cd /path/to/project
bb index
bb stats

Reindex changed files only

bb index --changed

Incremental: only missing or changed files are reparsed.

Clean rebuild

bb index --force

Wipes the existing index for this project and rebuilds in place.

Re-run derived phases only

bb index --post

Re-runs relationship resolution, enrichment, and health phases without reparsing source files — the remediation for stale derived data.

Resume an interrupted run

bb index --resume

Embeddings setup

Semantic search (bb_ask semantic mode) uses embedding vectors. Without a provider key, the indexer still works — semantic search just falls back to weaker local vectors, and the CLI tells you so honestly.

bb setup        # interactive: provider, API key, model
bb setup show   # inspect config — the key is shown as a fingerprint only

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.

Keys stay on your machine

The API key is stored with owner-only permissions (0600) and is never sent to any AI agent — tools see a fingerprint only.

Agent tools (11)

Backbencher exposes 11 public MCP tools for indexed discovery, analysis, documentation, guarded mutation, diagnostics, security analysis, migration planning, and graph export. These are tool calls an MCP client invokes — not shell subcommands.

Tool	Purpose
bb_analyze	Unified evidence-backed analysis over graph relationships, dependencies, statistics, complexity, impact, and test intelligence.
bb_ask	Answer a question about the codebase using semantic search over the index.
bb_doc	Generate read-only, evidence-backed documentation with resolvable citations and a freshness block over the cited files.
bb_edit	Unified, validated source mutation.
bb_health	Unified index health: file/symbol/relationship/imports counts, embedding model + coverage, schema version, runtime, and file freshness.
bb_index	Reindex a file or directory so the index reflects edits immediately (agent-fresh).
bb_migrate	Read-only single or batch migration planning with dependency order, explicit effort methodology, library mappings, risks, truncation, and unsupported cases.
bb_patterns	Detect orphaned code, framework patterns, and anti-patterns, with staleness markers when a finding's file changed after indexing.
bb_search	Unified indexed retrieval for symbol lists, content, exact symbol source, or files.
bb_security	Cross-language security scan: SQL injection, XSS, command injection, hardcoded secrets, weak crypto.
bb_visualize	Scoped dependency and architecture visualization over the canonical graph engine, with explicit filters, provenance, truncation, machine-readable JSON, and self-contained HTML.

Full schemas, defaults, safety behavior, and limitations

From the terminal, run any tool with JSON arguments:

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

MCP server

bb mcp starts the Backbencher MCP server over stdio. Point any MCP client at it — Claude Code, Cursor, VS Code, opencode, and others:

# Claude Code
claude mcp add backbencher -- bb mcp --dir /path/to/project

# Generic MCP client configuration
{
  "mcpServers": {
    "backbencher": {
      "command": "bb",
      "args": ["mcp", "--dir", "/path/to/project"]
    }
  }
}

bb mcp starts a server, it does not configure clients

bb mcp is the server process. Client registration happens in your MCP client's own configuration, as shown above.

CLI reference

All 11 top-level commands — run bb <command> --help for flags:

bb index [dir]

index a project (--changed, --force, --post, --resume, --file)

bb stats [dir]

index counts: files, symbols, relationships, embeddings

bb status [dir]

in-flight/last-run index state and per-phase timings

bb search <query>

search the index (limit, language filters)

bb health [dir]

index health and freshness

bb projects

list every indexed project; remove with --remove

bb setup

embedding provider setup; `bb setup show` inspects config

bb doctor

diagnose embedding setup and index consistency

bb tool <name>

run one of the public tools with JSON arguments

bb mcp

start the MCP server over stdio

bb version

print the bb version

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?

Troubleshooting

Search results look stale

bb index --changed   # or
bb index --post      # re-run derived phases without re-parsing

Tool results carry a freshness block with the exact remediation command.

Repair a corrupted index

bb index --force

Wipes and rebuilds this project's index in place.

Semantic search is weak or missing

bb setup show   # is a provider configured?
bb doctor       # is the setup consistent?

Without embeddings, semantic modes fall back to local vectors and say so. Configure a provider with bb setup.

Interrupted index run

bb status          # see where it stopped
bb index --resume  # continue from the checkpoint

Verbose diagnostics

bb --verbose <command>

Shows debug logs and per-file worker/WASM lines. bb --quiet suppresses informational output.

Upgrade caveat

The inherited bb upgrade implementation currently targets upstream OpenCode release channels rather than Backbencher releases. Until that is corrected, rerun the installer or set its VERSION environment variable to a published Backbencher release.