Turn any codebase into a durable, searchable knowledge graph—and give your coding agent MCP tools to query it—locally, privately, and in about two minutes.
~2 minutes No account or API key Python 3.11+ and uv
01
Prerequisites
Make sure you’re ready
RepoBrain needs Python 3.11 or newer and uv, a fast Python package manager. There's nothing to pip install by hand — uv handles isolated environments for you, either on demand each time or as a real installed command (next step).
Terminal
$python3 --version
uv --version
i
Don’t have uv yet? Install uv, then return here. Python can be downloaded from python.org. Prefer a source checkout with an explicit virtualenv? See the README for the uv venv / editable-install path.
02
Shortcut
Put repobrain on your PATH
RepoBrain isn't published to PyPI yet, so a bare uvx repobrain won't resolve on its own. Run this once with uv tool install and you get a real repobrain command — the same way code or subl work — so every command from here on stays short.
Open a new terminal afterward. Not found? Run uv tool update-shell and try again. Refresh to the latest commit any time with the same command plus --reinstall; remove it with uv tool uninstall repobrain. Skipping this step is fine too — just prefix every command below with uvx --from git+https://github.com/jakegibs617/RepoBrain instead of plain uvx.
03
Index
Build your knowledge graph
From the project you want RepoBrain to understand, run one command. It scans the project and connects its files, symbols, imports, calls, tests, docs, and environment variables.
Terminal · project root
$repobrain index .
Your graph lives in .repobrain/repobrain.sqlite inside the project. Nothing leaves your machine, and re-running this command later only re-parses what changed.
04
Connect
Give your agent MCP tools
This is the actual point of RepoBrain: your AI coding agent gets first-class access to the graph you just built. One command writes a repository-scoped .mcp.json entry, a marker-owned CLAUDE.md section, and (for Claude Code) an idempotent SessionStart hook.
Terminal · project root
$repobrain install-agent .
i
Add --git-hooks to also keep the index fresh after every commit and merge. Restart your agent client afterward, then confirm the tools are registered with cat .mcp.json. Run the same command with uninstall-agent . any time to remove only RepoBrain-owned entries.
05
Orient
Generate a session brief
A stale or silent knowledge base doesn’t help anyone. brief produces a token-budgeted orientation pack — purpose, subsystems, entrypoints, open assumptions, and recent memory — grounded entirely in what was just indexed, not a guess.
Terminal
$repobrain brief --budget 2000
Once install-agent has run, a compatible agent client gets this automatically at session start — you shouldn’t need to run it by hand day to day.
06
Explore
Ask your first question
Search the indexed project, look up a symbol, or ask RepoBrain to explain a file — the same graph facts your agent's MCP tools now use.
RepoBrain is a graph of what your codebase actually is — not a summary someone (or something) wrote about it once and forgot to update.
Does RepoBrain store an AI's interpretation of my code, or the actual code?
The core design
Both, deliberately kept apart. Every fact in the graph — symbols, imports, calls, env reads — is re-parsed from source on every index run, tagged with a confidence score and which extractor produced it. Nothing here is a stale guess: unchanged files aren't even re-read, and changed ones are rebuilt from scratch.
Interpretation lives in its own lane. When your agent forms an opinion — a decision, an assumption, an open question — it can write that into the graph as its own node type, anchored to the exact file and line it's about. repobrain memory verify then rechecks every one of those anchors against current source and marks it verified, drifted, or invalidated. So the graph never lets an old assumption quietly pass as still-true fact.
Does RepoBrain call an LLM or send my code anywhere?
No. Indexing, parsing, and search all run locally with no API keys and no network calls. The graph lives in a single SQLite file inside your project (.repobrain/repobrain.sqlite) and never leaves your machine unless you copy it yourself.
Does the graph go stale as I keep coding?
Every read command checks freshness before answering — if source files changed since the last index, it re-indexes automatically (or refuses to answer, in strict mode) before returning anything. Re-indexing is incremental: only files whose content hash changed get re-parsed, so this stays fast even on large repos.
Is RepoBrain on PyPI yet?
Not yet — it's still pre-release. Until it's published, run it straight from GitHub with uvx --from git+https://github.com/jakegibs617/RepoBrain repobrain index .
Tired of typing the --from git+… part? That's what step 2 above is for — a one-time uv tool install that gives you a real repobrain command on your PATH, the same way code or subl work. See the README for an always-fresh alternative that skips the install step entirely.
What languages does it understand?
Symbol, import, call, and env-var extraction for Python, JavaScript, TypeScript, PHP, Bash, Go, Java, and Ruby, plus generic parsing for Markdown, YAML, and dotenv files. See the supported-languages table for exactly what's resolved per language.
Will it modify my source code?
No. RepoBrain only reads your files and writes to its own .repobrain/ directory (plus an optional .mcp.json entry and CLAUDE.md section if you run install-agent). It never edits your source.