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, or as a Python library.

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 nomic-embed-text                          # local embeddings, one time
export MEGABRAIN_EMBED_BASE_URL=http://localhost:11434/v1
export MEGABRAIN_EMBED_MODEL=nomic-embed-text

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.

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), megabrain_get, megabrain_chunks, megabrain_index.

Commands

megabrain index  ~/repo                          # build / update the index
megabrain ask    ~/repo "how does X work"        # narrated walkthrough + real code
megabrain query  ~/repo "retry logic"            # raw code map, no LLM (~200 ms)
megabrain get    ~/repo src/x.py --symbol Foo    # one file or symbol
megabrain serve-api ~/repo                       # long-running HTTP API (warm state)

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.

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). The full provider matrix — native APIs, hybrid, fully-local GPU — is in docs/ARCHITECTURE.md.

How it works

Languages: Python · JS/TS · Markdown built in; Ruby · Go · Rust · PHP with pip install 'megabrain[languages]'.

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/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}