Backbencher (bb)

AST-Native Code Intelligence for AI

Index your entire codebase into a local SQLite brain. 25+ tools give AI byte-precise access to symbols, call graphs, relationships, and cross-language intelligence across 40+ languages.

Website • Documentation

bb parses your entire codebase using Tree-sitter AST parsing and stores every symbol, relationship, and import in a local SQLite database. 25+ brain tools (bb_*) give the AI byte-precise, AST-aware access to your code.

# Install
curl -fsSL https://raw.githubusercontent.com/ishaq2321/bb/master/install.sh | bash

# Index your project
cd your-project
bb brain --force          # first time (~3 min for 4,000 files)
bb brain                   # subsequent runs (seconds, incremental)

# Load the skill (teaches AI to use brain tools)
bb skill install https://github.com/ishaq2321/bb/blob/master/skill/SKILL.md

After indexing, the AI gets 25+ brain tools:

Every tool is AST-aware — byte-precise boundaries, LSP-validated, cross-language by default.

bb_ask uses embedded word vectors that work offline with no setup. The vocabulary adapts to your project automatically.

$ bb brain --force
...
Generating semantic embeddings... 20,000 vectors (word vectors — offline)

For higher quality (optional), add an API key to bb.json:

{
  "provider": { "openai": { "apiKey": "sk-..." } },
  "embedding_model": "openai/text-embedding-3-small"
}

Cost: ~$0.02 per 1M tokens. Best quality.

{
  "provider": { "google": { "apiKey": "AIzaSy..." } },
  "embedding_model": "google/gemini-embedding-001"
}

Get a key at aistudio.google.com/apikey. Free tier: 1,500 requests/day.

{
  "provider": { "mistral": { "apiKey": "..." } },
  "embedding_model": "mistral/mistral-embed"
}

{
  "provider": { "cohere": { "apiKey": "..." } },
  "embedding_model": "cohere/embed-english-v3.0"
}

Works with Azure, NVIDIA NIM, Google Vertex AI, self-hosted models, or any service exposing /v1/embeddings:

{
  "provider": { "nvidia": { "apiKey": "...", "baseURL": "https://..." } },
  "embedding_model": "nvidia/nv-embedqa-e5-v5"
}

After configuring any provider, run bb brain --post to regenerate embeddings.

Config lives in bb.json at your project root. This file is not created automatically — create it only to configure providers or override defaults.

{
  "provider": {
    "openai": { "apiKey": "sk-..." },
    "google": { "apiKey": "AIzaSy..." },
    "mistral": { "apiKey": "..." }
  },
  "embedding_model": "openai/text-embedding-3-small"
}

• Location: ~/.local/share/opencode/brain/<git-hash>/brain.db
• Size: ~700MB for 4,000 files / 588K symbols
• Incremental: Only re-indexes changed files (hash-based detection)
• Force re-index: bb brain --force
• Post-processing only: bb brain --post (resolution + embeddings + patterns)

TypeScript, JavaScript, Python, Dart, Go, Rust, Java, Kotlin, Swift, C, C++, C#, F#, Ruby, PHP, Elixir, Haskell, Lua, Zig, Scala, R, SQL, Bash, PowerShell, HTML, CSS, JSON, YAML, TOML, XML, Markdown, Vue, Erlang, Objective-C, Perl — 40+ languages via Tree-sitter parsers.

# macOS & Linux
curl -fsSL https://raw.githubusercontent.com/ishaq2321/bb/master/install.sh | bash

# Windows (PowerShell)
irm https://backbencher.cc/install.ps1 | iex

# Manual (from releases)
# Download from https://github.com/ishaq2321/bb/releases
chmod +x bb-* && sudo mv bb-* /usr/local/bin/bb

Current: 1.0.17

• GitHub Issues
• support@backbencher.cc