bb

bb v0.3.0 — local-first code intelligence

Your codebase,
understood locally.

bb parses source files with tree-sitter AST grammars into one project-local SQLite index — precise symbol extraction, code search, call-graph queries, and relationship mapping over 49 languages. No cloud, no upload.

Your coding agents reach the same index through 16 MCP tools — bb_search, bb_analyze, bb_ask — with exact source bounds and guarded edits.

Install bbBrowse the 16 tools
zsh — bb

$ bb --version

0.3.0

$ bb --help

Usage: bb [options] [command]

Backbencher Brain — universal code intelligence (40+ languages)

Options:

-v, --version output the version number

-h, --help display help for command

Commands:

tool <name> run one of the public tools with JSON args

index [dir] index a project (default: current dir)

setup embedding provider setup (API key, model)

doctor [opts] diagnose setup and index consistency

stats [dir] query index counts anytime

search <query> search the index (symbol, content, file)

health [dir] index health and freshness

mcp [opts] start the MCP server over stdio

$

Fig. 01 — bb --version and bb --help, verbatim from the CLI
49
Languages Indexed
46
Dedicated tree-sitter parsers
16
Agent Tools
15
DB Tables

bb 0.3.0 · 49 Languages Indexed · 46 dedicated tree-sitter parsers · 16 Agent Tools · 15 SQLite tables

01 · The brain

From source files to a guarded code graph.

One pipeline: parse with AST precision, persist a relational code graph, serve queries with explicit fallbacks, and mutate source only through guarded, index-verified operations.

  1. 01

    Discover & Parse

    Discovers eligible source files, applies project exclusions, and parses them in fault-contained workers.

    DISCOVERRespecting .gitignore, .bbignore, and generated paths

    WORKERSParsing changed files in isolated subprocesses

    STATUSRecording clean, recovered, or partial parse state

  2. 02

    Persist the Code Graph

    Stores files, symbols, source bounds, imports, relationships, patterns, taint flows, and index health in project-local SQLite.

    SQLITECommitting one file result per transaction

    SYMBOLSWriting names, kinds, owners, and byte bounds

    EDGESResolving unambiguous relationship targets

  3. 03

    Query & Enrich

    Serves symbol reads and graph queries, then layers on impact, patterns, security findings, health, and semantic search where data exists.

    SELECTReading only the indexed symbol range

    GRAPHTraversing callers, callees, and import edges

    FALLBACKUsing keyword search when embeddings are unavailable

  4. 04

    Guard Source Changes

    Uses fresh indexed coordinates to update, insert, delete, rename, or create source, with safety behavior specific to each tool.

    PREFLIGHTRefreshing stale bounds before mutation

    PATCHApplying an indexed byte-range operation

    REINDEXSynchronizing the accepted or restored file

Guarantees vary by parser, index freshness, tool, and available LSP — the pipeline reports what actually happened instead of pretending every file or edit has identical guarantees.

02 · Language coverage

Indexed once, in the languages you ship.

46 dedicated tree-sitter parsers across 49 languages and file types. Depth varies by grammar availability and file size — the index records what it could parse instead of pretending otherwise.

45 display families · registry-driven

  • TypeScript
  • JavaScript
  • Python
  • Rust
  • Go
  • Java
  • C++
  • C
  • C#
  • Ruby
  • PHP
  • Swift
  • Kotlin
  • Dart
  • Elixir
  • Clojure
  • Haskell
  • Scala
  • Lua
  • R
  • Bash
  • SQL
  • HTML
  • CSS / SCSS
  • JSON
  • YAML
  • PowerShell
  • GraphQL
  • HCL / Terraform
  • Erlang
  • F#
  • Groovy
  • Vue
  • Svelte
  • Perl
  • Clean
  • Zig
  • Objective-C
  • Markdown
  • TOML
  • XML
  • Make
  • Protobuf
  • Nim
  • Visual Basic

Symbols + call graph

A dedicated analyzer plus resolved imports and call edges — your agent can trace callers, callees, and impact across these families.

TypeScript, Python, Rust, Go, Swift, Kotlin

Structural symbols

A dedicated analyzer records structure and semantics precisely, without a resolved call graph.

SQL, HTML, CSS, JSON, YAML, GraphQL

Generic pass

The grammar parses and the generic traversal records symbols — honest, but deliberately weaker depth.

TOML, Protobuf, Nim, Visual Basic

Browse the full register — 45 families, one graph
Application & systems
15
TypeScript
.ts, .tsx

call graph

functions · classes · interfaces · enums

JavaScript
.js, .jsx

call graph

functions · classes · methods

Python
.py

call graph

functions · classes · methods · types

Rust
.rs

call graph

functions · structs · traits · modules

Go
.go

call graph

functions · methods · interfaces · packages

Java
.java

call graph

classes · interfaces · methods · constructors

C++
.cpp, .h

call graph

classes · methods · namespaces · enums

C
.c, .h

call graph

functions · structs · enums · types

C#
.cs

call graph

classes · interfaces · events · methods

Swift
.swift

call graph

classes · protocols · methods · constructors

Kotlin
.kt

call graph

classes · interfaces · methods · constructors

Dart
.dart

call graph

classes · enums · methods · constructors

Zig
.zig

call graph

functions · structs · enums · constants

Objective-C
.m, .mm

call graph

classes · protocols · methods

Visual Basic
.vb

generic pass

grammar parses · generic key pass

Functional & declarative
8
Elixir
.ex, .exs

call graph

modules · functions · typespecs

Clojure
.clj

call graph

namespaces · functions · protocols

Haskell
.hs

call graph

modules · type classes · data types

Scala
.scala

call graph

classes · traits · methods · objects

Erlang
.erl, .hrl

call graph

modules · functions · macros · typespecs

F#
.fs, .fsx

call graph

modules · functions · types · methods

Clean
.icl, .dcl

call graph

modules · functions · types

Nim
.nim

generic pass

grammar parses · generic key pass

Scripting & shell
8
Ruby
.rb

call graph

classes · modules · methods

PHP
.php

call graph

classes · namespaces · methods · enums

Lua
.lua

call graph

functions · methods · variables

R
.r

call graph

functions · methods · classes

Bash
.sh

call graph

functions · variables · env constants

PowerShell
.ps1, .psm1

call graph

functions · classes · enums

Groovy
.groovy, .gsp

call graph

classes · interfaces · methods

Perl
.pl, .pm

call graph

packages · functions · methods

Web, data & config
14
SQL
.sql

structural

tables · views · procedures · columns

HTML
.html

structural

semantic elements · id anchors

CSS / SCSS
.css, .scss, .sass

structural

selectors · mixins · custom properties

JSON
.json

structural

object keys · nesting shape

YAML
.yml, .yaml

structural

hierarchical keys · values

GraphQL
.graphql, .gql

structural

types · interfaces · fields · operations

HCL / Terraform
.hcl, .tf

structural

resources · modules · variables

Vue
.vue

call graph

components · props · events · methods

Svelte
.svelte

call graph

components · methods · state

Markdown
.md

structural

heading hierarchy · sections

TOML
.toml

generic pass

grammar parses · generic key pass

XML
.xml

structural

elements · namespaces · attributes

Make
Makefile

structural

targets · variables

Protobuf
.proto

generic pass

grammar parses · generic key pass

Open the full language console

45 families · extensions · registry names · per-family depth on one page

03 · Agent toolkit

Every public tool your agent can already call.

Every tool is an MCP call over stdio — symbol reads, code search, graph queries, diagnostics, and guarded source edits, all bounded by the index.

All 16 tools · MCP over stdio

Discovery

bb_search

Unified lexical, content, exact-symbol, and file retrieval.

read-only · needs indexReference
Discovery

bb_ask

Natural-language answers and semantic matches.

read-only · needs indexReference
Diagnostics

bb_health

Unified index, schema, freshness, embeddings, runtime, integrity, and analysis history.

read-onlyReference
Analysis

bb_patterns

Pattern/orphan analysis with optional persisted run history.

read-only · needs indexReference
Diagnostics

bb_security

Cross-language findings with optional persisted run history.

read-only · needs indexReference
Diagnostics

bb_visualize

Scoped canonical dependency graphs with explicit truncation and provenance.

read-only · needs indexReference
Analysis

bb_migrate

Batch cross-language migration plans with ordering, methodology, and unsupported mappings.

read-only · needs indexReference
Analysis

bb_analyze

One typed analysis surface replacing standalone relationship and test intelligence names.

read-only · needs indexReference
Analysis

bb_doc

Cited Markdown or JSON documentation over indexed source and relationships.

read-only · needs indexReference
Operations

bb_edit

Unified safe source editing with preview, validation, rollback, and reindex.

writes to disk · needs indexReference
Operations

bb_index

Immediately refresh the index for a just-written/edited file or directory; mode=post re-derives relationships/taints/health without re-parsing.

writes to diskReference
Analysis

bb_graph

Per-symbol graph with per-edge evidence tiers — the agent view of the editor's graph panel.

read-only · needs indexReference
Analysis

bb_impact

Bounded impact with declared truncation — identical numbers to the editor's impact mode.

read-only · needs indexReference
Analysis

bb_cross_language

Stored cross-language pairs with declared absence — the agent view of the hover section.

read-only · needs indexReference
Analysis

bb_annotate

Agent note with enforced provenance, stored where the human reads.

writes to diskReference
Analysis

bb_annotations

Annotations with full provenance; absence declared.

read-onlyReference
Browse every tool & parameter schema

Names, purposes, mutability and index requirements above are registry-owned — the same source of truth the MCP server renders from.

04 · Why bb

Precise, local, and honest with your agents.

Local by default

bb never sends source to a server. The index is a SQLite file beside your project, and reading it offline is the normal case — code search and call-graph queries run without a network.

Honest about depth

Every tool reports what it actually knows. When no embedding model is configured, semantic search falls back to keywords and says so — the index never pretends to be richer than it is.

Agents call the same index

bb speaks MCP over stdio, so your coding agents run the same precise queries you do — symbol reads, impact analysis, and guarded edits, all with exact source bounds.