Documentation
Welcome to Backbencher (bb) - The Dual-Engine Codebase OS. Unlike traditional AI tools that blindly grep text, bb uses AST (Abstract Syntax Trees) to understand your code.
Installation
Backbencher is distributed as a standalone binary. No Node.js or Python required.
macOS & Linux
Windows (PowerShell)
Quickstart
1. Index your Brain (Required)
Navigate to your project directory and build the SQLite AST database.
cd your-project && bb brain index2. Launch Backbencher
Start the interactive terminal UI.
bb3. Connect Provider
Inside the TUI, type the slash command to configure your API keys (e.g. Anthropic, OpenAI).
/connect
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.
Native Brain Tools
Autonomous Usage
You do not need to call these tools manually. When you type a prompt (e.g., "Fix the auth logic in the login function"), the LLM autonomously selects these AST tools to search, extract, and update your code.
However, for power users, these commands are available in the CLI and TUI for manual surgical execution.
bb_search
Semantically and syntactically searches the project's native brain index using AST intelligence.
- Scope: project, functions, classes, semantic, exact_text
- Usage: Finding symbols, codebase exploration, dependency discovery.
bb_select
Fetches a compiled Context Package for a specific symbol using surgical AST precision. It dynamically extracts isolated snippets directly from the file.
- Usage: Replaces the primitive `read` tool. Used to understand exact implementations without wasting tokens on 2,000-line files.
bb_update
Semantically updates a function, class, or symbol by replacing it entirely based on exact Tree-sitter byte coordinates.
- Safety: Ensures zero collateral damage to surrounding indentation or logic.
- Usage: Rewriting discrete architectural symbols found via `bb_search`.
bb_relationships
Explores the dependency graph instantly using the SQLite brain.
- Features: Finds Callers, Callees, Class inheritance, and Impact analysis.
- Usage: "What will break if I change this function?"