Documentation
Welcome to Backbencher. Unlike traditional AI tools that search text, Backbencher uses AST (Abstract Syntax Trees) to understand your code structure.
Installation
Backbencher is distributed as a standalone binary. No Node.js or Python required.
macOS & Linux
Windows (PowerShell)
Quickstart
1. Index your brain
Navigate to your project. Run bb brain to index into the local SQLite brain. Only needed once — subsequent runs update incrementally.
cd your-project && bb brain2. Load bb-tools skill
The skill teaches AI to use 15 brain tools (bb_search, bb_select, bb_update). Without the skill, bb is just another OpenCode.
/skills bb-tools3. Launch & Chat
Start the TUI. The AI can now query your codebase via the brain.
bb4. Connect Provider
Configure your API keys inside the TUI.
/connect
🧠 The Brain
Local SQLite database — one per git project. 39 languages. Symbols, relationships, imports, cross-language bridges.
Symbols
Every function, class, method — byte-precise AST boundaries.
Relationships
Every call, import, inheritance — pre-computed call graphs.
Cross-Language
Python → JS, Dart → Swift — tracked across all languages.
Incremental
Only re-indexes changed files. 20K-file monorepo: under 1 second.
📋 The bb-tools Skill
Teaches AI to use 15 brain tools instead of grep/read/edit. Without it, bb is just another OpenCode.
Or permanently:
Upgrading Backbencher
Backbencher includes a built-in command to safely upgrade your standalone binary and dependencies to the latest release.
Auto-Upgrade Command
Run this anywhere in your terminal to fetch the latest version securely.
bb upgradeUse bb as an MCP Server
You can expose all of Backbencher's native AST intelligence (e.g., bb_select, bb_relationships) directly to your favorite GUI editor like Cursor or Claude Desktop using the Model Context Protocol (MCP).
Claude Desktop Configuration
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"backbencher": {
"command": "bb",
"args": ["mcp-server"]
}
}
}Availability
MCP server access is available to all Backbencher users. No license required.
Powered by Opencode
Backbencher is built on top of the Opencode framework. This means that all industry-standard configuration for LLMs, MCPs (Model Context Protocol), and Skills work exactly the same way.
Free Models Provided by OpenCode
Thanks to OpenCode! The free models provided in this tool are from OpenCode, not from us. We just used their open-source code to create bb, that's it. All credit for the free model access goes to them.
LLM Configuration
Easily switch between Anthropic, OpenAI, or local models via `/connect` or config files.
MCP Servers
Native support for Model Context Protocol. Connect your existing MCP tools instantly.
Brain Tools
You do not need to call these tools manually. The LLM autonomously selects the right tool when you type a prompt. These docs explain what each tool does so you understand the capabilities available.
bb_search
Search the AST-indexed brain for symbols, functions, classes, and files by name. Scopes: project, functions, classes, files. More precise than grep for named code elements.
bb_select
Read a specific symbol's code within AST byte bounds. Returns only the function body, not the entire file. Saves tokens. Includes callers and callees by default.
bb_update
Modify a symbol using AST-precise byte boundaries. Auto-cascades changes to all callers. LSP validates and auto-rolls back on errors.
bb_delete
Delete a symbol with cascade protection — blocks deletion if other symbols reference it. Auto-prunes orphaned imports.
bb_insert
Insert new code at a precise AST position relative to an existing symbol. Auto-injects required imports.
bb_write
Create a new file with automatic wiring into the project structure. Detects file type and auto-adds imports to parent files.
bb_refactor
Rename a symbol across the entire codebase. LSP primary, AST fallback. Automatically cascades to all callers.
bb_relationships
Analyze call graphs and dependencies. 9 analysis types: callers, callees, impact, test coverage, imports, exports, and more.
bb_patterns
Detect code patterns and anti-patterns: orphaned code, god classes, circular dependencies, dead code, complexity violations.
bb_ask
Ask questions about the codebase. Modes: quick_answer (DB stats) and semantic_search (similar code).
bb_security
Scan for vulnerabilities using AST data flow analysis: SQL injection, XSS, hardcoded secrets, weak crypto.
bb_visualize
Generate interactive HTML dependency graphs. Self-contained 3D force-graph that opens in any browser.
bb_migrate
Plan cross-language migrations with dependency ordering and effort estimates. Planning tool, not code generator.
bb_refresh
Rebuild the brain. Runs asynchronously. Use when tools return empty results.
bb_health
Report brain status: files, symbols, relationships, LSP availability, parser pool, uptime.