How backbencher-hq/backbencher-brain works
Backbencher Brain (bb) indexes a project’s source into a per-project SQLite database, then provides code-intelligence results through CLI, MCP, LSP, and library-facing runtime features. The main workflow is source parsing and indexing, followed by graph, search, and evidence-based queries; health, semantic retrieval, visualization, editing, security analysis, and other documented capabilities are separate branches. The excerpts support key orchestration and storage relationships, but not every subsystem’s internal wiring, so those links are limited to README-documented flows.
Main entry points: index.ts CLI · database.ts Project Database · server.ts MCP Server · parallel-indexer.ts Parallel Indexer
Components 22
User Interfaces
- CLI
src/cli/index.ts - MCP Server
src/mcp/server.ts - Tool Registry
src/mcp/tool-registry.ts - LSP Server
src/lsp/server.ts
Indexing
- Parallel Indexer
src/ast/parallel-indexer.ts - Language Detection
src/ast/language-detection.ts - AST Engine
src/ast/engine.ts - Tree-sitter Grammars
grammars
Index and Contracts
- Project Database
src/brain/database.ts - Project Identity
src/util/project-id.ts - Intelligence Contracts
src/intelligence/contracts.ts - Evidence Provenance
src/intelligence/evidence.ts
Intelligence
- Relationship Graph
src/intelligence/graph/graph-engine.ts - Search
src/intelligence/search - Semantic Retrieval
src/brain/semantic/engine.ts - Health and Freshness
src/intelligence/health/health-provider.ts - Visualization
src/intelligence/visualization/visualization-engine.ts
Analysis and Maintenance
- Code Editing
src/intelligence/edit/edit-engine.ts - Security Analysis
src/intelligence/security/rebuild/engine.ts - Pattern Analysis
src/intelligence/patterns/orphans.ts - Migration
src/intelligence/migration
Other components
- Repository User
Connections 32
- Repository User → CLI: runs commands
README.md - Repository User → MCP Server: connects host
README.md - Repository User → LSP Server: uses editor
README.md - CLI → Parallel Indexer: indexes project
src/cli/index.ts - Parallel Indexer → Language Detection: detects languages
- Parallel Indexer → AST Engine: parses files
- AST Engine → Tree-sitter Grammars: uses parsers
README.md - Parallel Indexer → Project Database: stores index
README.md - CLI → Project Database: opens index
src/cli/index.ts - MCP Server → Project Identity: resolves project
src/mcp/server.ts - MCP Server → Project Database: checks index
src/mcp/server.ts - MCP Server → Tool Registry: registers tools
src/mcp/server.ts - LSP Server → Project Database: opens index
src/lsp/server.ts - LSP Server → Project Identity: resolves project
src/lsp/server.ts - Project Database → Project Identity: resolves data path
src/brain/database.ts - CLI → Relationship Graph: queries relationships
- CLI → Search: searches index
README.md - CLI → Health and Freshness: reports health
src/cli/index.ts - CLI → Semantic Retrieval: requests embeddings
src/cli/index.ts - Project Database → Relationship Graph: supplies index rows
src/intelligence/graph/graph-engine.ts - Project Database → Visualization: supplies index rows
src/intelligence/visualization/visualization-engine.ts - Project Database → Health and Freshness: supplies index state
src/intelligence/health/health-provider.ts - Project Database → Pattern Analysis: supplies index rows
src/intelligence/patterns/orphans.ts - Project Database → Semantic Retrieval: stores embeddings
src/brain/semantic/engine.ts - Semantic Retrieval → Intelligence Contracts: returns answers
- Relationship Graph → Intelligence Contracts: returns relationships
src/intelligence/graph/graph-engine.ts - Intelligence Contracts → Evidence Provenance: carries provenance
src/intelligence/contracts.ts - CLI → Visualization: renders index
README.md - CLI → Code Editing: edits source
README.md - CLI → Security Analysis: analyzes security
README.md - CLI → Pattern Analysis: finds patterns
README.md - CLI → Migration: migrates code
README.md