megabrain

Ask a codebase a question. Get the exact code back.

Point megabrain at a repo and ask "how does auth work" in plain English. It finds all the related code — in ~200 ms, using no LLM, just math on embeddings — and an LLM narrates a walkthrough with the real code spliced in from disk. Nothing is invented: every line shown is copied verbatim.

Use it from the terminal, as an MCP server inside Claude Code, as a Python library, or as a full local web app.

🖥️ megabrain studio — the whole engine, in your browser

One command turns megabrain into a local studio — nothing canned, every pixel driven by the live engine:

megabrain serve-api ~/repo        #  → open http://localhost:2134

• Search — every related file ranked in ~200 ms; click one for a chunk heatmap where signal glows and noise dims, code syntax-highlighted.
• Prune — the money shot: what the engine read vs what it ignored, side by side.
• Ask — watch a broad question fan out into parallel sub-agents, their tool calls and prose streaming into per-agent cards, then a synthesis with the real code spliced in as it types.
• Providers, live — Claude SDK · OpenRouter · Ollama, auto-detected. Switch the narrator without leaving the page, pick the model, and start ollama serve in one click to go fully local.
• Add a repo → it scans first — you SEE exactly what will index and what's skipped and why (.gitignore · vendored · generated · too-big), edit the .megabrainignore, then a live progress bar indexes it file by file.
• Embeddings you can see — which model each index used, and re-index with another (cloud pplx or a local, code-tuned jina) behind the same bar — the query embedding switches to match, so search keeps working.

Keyboard-driven, dark/light, zero build step, no CDN. --no-ui serves the JSON API only.

Quickstart — the easy path, no API keys

Everything runs on your machine: ask narrates on your Claude Code subscription, embeddings run locally on Ollama. No cloud keys.

pip install 'megabrain[claude]'                      # engine + Claude Code narration

ollama pull unclemusclez/jina-embeddings-v2-base-code # local, code-tuned embeddings, one time
export MEGABRAIN_EMBED_BASE_URL=http://localhost:11434/v1
export MEGABRAIN_EMBED_MODEL=unclemusclez/jina-embeddings-v2-base-code

megabrain index ~/your/repo                           # once — incremental after
megabrain ask   ~/your/repo "how does auth work end to end"

ask uses your logged-in claude CLI (free on your plan); embeddings never leave your machine. No OpenRouter, no Anthropic key.

Which model? On Claude Code, ask narrates with Haiku by default (fast + cheap on your plan). Bump it with a Claude alias — export MEGABRAIN_ASK_MODEL=sonnet (or opus). ⚠️ On the claude provider this must be a Claude model (haiku/sonnet/ opus/a claude-* id), not an OpenRouter slug like google/….

Inside Claude Code

Register it as an MCP server and research any indexed repo without leaving Claude Code:

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

Then use megabrain_ask / megabrain_query instead of grep + Read chains — one call replaces minutes of file-crawling. Tools: megabrain_ask (narrated walkthrough), megabrain_query (raw code map, no LLM — pass prune_noise: true for just the signal chunks worth reading, ranked flat), megabrain_get, megabrain_chunks, megabrain_index.

Commands

megabrain index  ~/repo                          # build / update the index
megabrain scan   ~/repo                          # census: what WOULD index + what's skipped & why
megabrain ask    ~/repo "how does X work"        # narrated walkthrough + real code
megabrain query  ~/repo "retry logic"            # raw code map, no LLM (~200 ms)
megabrain query  ~/repo "retry logic" --prune    # flat signal-only chunks, no LLM (drops the noise)
megabrain get    ~/repo src/x.py --symbol Foo    # one file or symbol
megabrain forge  ~/repo                          # teach it your repo's file types (below)
megabrain serve-api ~/repo                       # HTTP API + the studio web UI at /

Scope to a sub-folder (~/repo/src/auth), search several repos at once (~/a,~/b), and the index auto-refreshes when files change on disk.

megabrain serve-api ~/repo also serves megabrain studio (the web UI, above) at /. And megabrain scan is the studio's add-repo census on the CLI — what would index and everything skipped with a reason (.gitignore · vendored · generated · too-big): --write applies the proposed .megabrainignore, and megabrain index --scan indexes with those smart filters on (a plain index stays byte-identical).

Rather use the cloud?

No Claude Code or Ollama? One key runs everything through OpenRouter — embeddings and narration — with sensible defaults:

export OPENROUTER_API_KEY=...
megabrain ask ~/repo "how does X work"

megabrain auto-picks the narrator: Claude when its SDK is installed, otherwise OpenRouter. Embeddings always go through OpenRouter or a local endpoint (Anthropic has no embeddings API).

Pin the provider and models with env vars (any OpenRouter slug):

export MEGABRAIN_CHAT_PROVIDER=openrouter                          # pin openrouter (skip claude auto-pick)
export MEGABRAIN_ASK_MODEL=google/gemini-3.1-flash-lite-preview    # the `ask` narration model
export MEGABRAIN_EMBED_MODEL=perplexity/pplx-embed-v1-0.6b         # the embedding model

The full provider matrix — native APIs, hybrid, fully-local GPU, per-provider defaults — is in docs/ARCHITECTURE.md.

100% open-source stack (measured, no closed-weight anything)

Every default above uses a proprietary model somewhere (pplx embeddings, Gemini/Claude narration). If you want zero closed weights — private code, an air-gapped box, or just principle — this combo is measured, not a guess, and holds up:

# 1. embeddings — Apache 2.0, code-tuned, runs on your machine, $0
ollama serve
ollama pull unclemusclez/jina-embeddings-v2-base-code    # 322 MB, one time
export MEGABRAIN_EMBED_BASE_URL=http://localhost:11434/v1
export MEGABRAIN_EMBED_MODEL=unclemusclez/jina-embeddings-v2-base-code

# 2. narration — Apache 2.0 (Qwen), via OpenRouter (or self-host on the same Ollama)
export MEGABRAIN_CHAT_PROVIDER=openrouter
export MEGABRAIN_ASK_MODEL=qwen/qwen3-coder

megabrain index ~/your/repo --force
megabrain ask   ~/your/repo "how does X work"

Retrieval recall (R@1 on a 22-question golden set, sdk-server — does the right file land #1):

Does ask actually still work? Ran the same two real questions against sdk-server with this exact stack:

• "where is barge-in handled when the user interrupts mid-speech" → correctly narrated from turn_controller.py, citing 4 files total (event_bus.py, bot_handler.py, webhooks.py too) — broader than the closed-default run.
• "how does an inbound websocket client get authenticated" → correctly narrated from transports/client/handler.py, the same file the closed stack found.

Both answers were grounded (every code block spliced verbatim, nothing invented) and landed on the right file — the open stack is a real, usable alternative, not a token gesture. The one real cost: qwen/qwen3-coder narrates in ~20-25 s per ask vs ~6 s for Gemini Flash — output-bound, not retrieval-bound, so it's the same trade-off as the cloud cheap-vs-fast pick. qwen3-coder also runs on the same local Ollama for a fully air-gapped setup (no OpenRouter call at all) — just slower without a GPU. Full comparison + a weaker general-purpose local embedder (e5-large, 0.364 R@1) in docs/GUIDE.md §2b.

How it works

Languages: Python · JS/TS · Markdown built in; Ruby · Go · Rust · PHP with pip install 'megabrain[languages]'; anything else via megabrain forge (below).

forge — megabrain writes its own chunkers

Repos carry more than code: .toml, .yaml, .astro, .proto, private DSLs… Anything outside the registry is invisible to retrieval. megabrain forge fixes that per repo:

megabrain forge ~/repo --list        # census: which text file types aren't indexed (free)
megabrain forge ~/repo               # LLM-write a chunking strategy per type, validate, install
megabrain forge ~/repo --dry-run     # show the generated code without installing

For each uncovered extension, an LLM (same provider stack as ask) writes a ChunkStrategy from the contract source + real sample files, and it is only accepted after chunking every matching file in the repo with a clean exact-line partition (validate_partition — failures feed a repair loop, and nothing unvetted ever installs). The vetted module lands in .megabrain/strategies/<ext>.py, sha-recorded in a user-level trust store (~/.megabrain/trust.json), and from then on every index — including the 60 s auto-refresh — loads it automatically. Hand-written strategies work the same way: drop the file in .megabrain/strategies/ and approve it with megabrain trust ~/repo.

Real run on pallets/click: forge detected .toml (11 files) and .yaml (8 workflows), generated both strategies on the first attempt (~28 s total), and "which workflow runs the test suite?" went from missing entirely to ranking .github/workflows/tests.yaml #1.

--specialize — measure a hand-written chunker (no LLM)

For a file type the engine ALREADY reads but chunks poorly (a giant lookup table blobs; a class of many tiny methods merges), you can hand-write a better strategy and have the engine measure it before it installs:

megabrain forge ~/repo --specialize          # census: covered files the built-in chunks poorly
# write a ChunkStrategy into .megabrain/strategies/<ext>.py, then gate it:
python -c "from megabrain.forge.specialize import gate_strategy; \
           print(gate_strategy('~/repo', open('strat.py').read(), '.py'))"

gate_strategy indexes the built-in vs your candidate for real, scores span-IoU

• hit@1 on neutral probes over every file the candidate changes, and installs (trust-gated) only if it beats a literature-tuned baseline — never on a whisper of improvement.

We tried letting an LLM write these and removed it. Across four repos the generated chunkers lost to a five-line deterministic recipe. And the deeper, measured finding: on a real query set (the sdk-server golden) tighter chunks LOWER retrieval ranking — the 4000-char merge concentrates a file's evidence and that is what wins R@1 (4000 → 0.86, 2000 → 0.82, blob-split → 0.77). Tighter chunks help navigation (fewer lines to read) but not retrieval. The built-in default is a genuine optimum; leave it alone unless you measure a win. Specialization is for the rare pathological file, gated hard.

flows — self-caching workflow retrieval (opt-in, off by default)

Every ask synthesizes a cross-file workflow ("VAD detects speech → TurnController.on_vad_start → cancel TTS") that the engine used to discard. Turn the flow cache on and it keeps them: the next related question — even worded completely differently — retrieves the whole workflow at once.

megabrain ask ~/repo "how does X work"       # unchanged: flows are OFF by default
megabrain flows ~/repo --enable              # opt in for this repo; asks now cache their flows
megabrain index ~/repo --warm-flows 12       # or pre-fill: discover the repo's 12 top workflows now
megabrain flows ~/repo                        # list what's cached · --clear to reset

• Off by default — plain query/ask behave byte-for-byte as before, at zero cost. It's a mode a team turns on so its megabrain accumulates the repo's workflows from use (great for onboarding).
• Rules intact: the LLM + the one embed happen at ask time (write path); the read path is pure cosine. Flows only add their source files to the bundle when missing (never displace real files → completeness only rises), and the narrator gets the cached flow as non-citable context. Any flow whose cited files change sha is pruned on the next index — a stale walkthrough can't outlive its code, and ask splices real code regardless.

Validated on sdk-server: --warm-flows 5 discovered and cached the system's main workflows; a paraphrase ("how does the bot stop talking when the user cuts in") retrieved the barge-in flow cached from a differently-worded question.

See it live

bernardocastro.dev/megabrain — search 7 popular open-source repos and watch the engine rank the files and pick the exact code chunks, live. Or run it locally: python examples/webui/server.py.

Learn more

• docs/GUIDE.md — step-by-step: providers, indexing, the 2000-vs-4000 budget choice, custom chunkers, and the flow cache
• docs/ARCHITECTURE.md — the full design, the locked rules, and the measurements behind them
• examples/ — programmatic API · a custom .sql chunker · the web demo
• CONTRIBUTING.md — the best first PR is a new language

_{MIT · github.com/bernatch22/megabrain}