megabrain

One call returns all the code related to a question
— explained like a senior engineer, with the real code spliced in.

megabrain is a local code-intelligence engine. It replaces minutes of file-by-file crawling — grep, read, explore-agent chains — with a single grounded answer. Index a repo once; every later question retrieves all the related code and stitches it into a walkthrough narrated by an LLM that can only point at code, never rewrite it — so nothing is hallucinated.

Install

pip install megabrain                 # core: Python · TS/JS · markdown
pip install 'megabrain[languages]'    # + Ruby · Go · Rust

Or from a clone, for development:

git clone https://github.com/pinecall/megabrain.git && cd megabrain
pip install -e .

Keys are read from the environment (with a ~/.zshrc fallback):

export PERPLEXITY_API_KEY=...   # required — embeddings
export ANTHROPIC_API_KEY=...    # only for `ask` and `--best`

Usage

megabrain index  ~/repo                                      # incremental (sha256), no daemon
megabrain ask    ~/repo "how does auth work end to end"      # walkthrough + real code (~6–20s)
megabrain ask    ~/repo "how do I configure X" --docs        # explain the docs instead of code
megabrain query  ~/repo "request retry logic"                # raw code map, no LLM (~200ms)
megabrain get    ~/repo src/x.py --symbol Class.method       # one file or symbol
megabrain serve-api ~/repo --port 2134                       # long-running JSON API (warm state)

Indexes code (.py · .ts · .tsx · .js · .jsx · .mjs · .cjs · Ruby · Go · Rust) and markdown (.md · .markdown · .mdx) through a strategy registry — adding a language or content type is a config entry, not a branch in the indexer.

How it works

A three-stage pipeline. Only ask calls an LLM — and only to narrate.

Because the model only emits citations and the engine splices code from disk, code cannot be hallucinated or rewritten.

MCP

Use it from Claude Code or any MCP client:

claude mcp add megabrain -- python3 -m megabrain.mcp_server

Tools: megabrain_ask (primary), megabrain_query, megabrain_get, megabrain_index. The server auto-refreshes a stale index before answering, so results always match disk.

HTTP API

serve-api keeps the index warm in memory and serves retrieval over HTTP (stdlib only — no framework). Embed it in any app, or front a static site with semantic search.

megabrain serve-api ~/repo --port 2134 [--host 0.0.0.0] [--cors https://site] [--no-llm]

State loads once and reloads only when the index changes on disk, so each query skips the SQLite matrix load. Binds localhost by default (front it with a reverse proxy); --cors opts into a browser origin.

Design

Every choice below is backed by an internal golden set (30 verified queries):

Engine retrieval (internal golden set): R@1 0.86 · bundle_full 1.00 · p50 8 ms warm. SWE-bench Lite localization (no training): retrieval Acc@1 ≈ 0.52 / @5 ≈ 0.83 — on par with the trained CodeRankEmbed retriever.

Project layout

megabrain/   engine — chunkers, embeddings, SQLite store, graph, indexer, query, ask, serve, cli, mcp_server
evals/       golden.json (30 verified queries) + swebench harness
tests/       engine + chunker gates

_{github.com/pinecall/megabrain}