RepoBrain: a cross-IDE knowledge layer for grounded codebase Q&A

The problem RepoBrain targets: context quality, not model choice

The README states the premise directly: an AI agent's capability ceiling equals the quality of context it can read. In practice that means an assistant handed a repo-wide grep spends its turns hunting for the right file, and a 5000-line CLAUDE.md gets read once and half-forgotten. RepoBrain's answer is to precompute a knowledge layer and route questions into it instead of letting the model wander the tree.

The intended user is someone who already works in an AI IDE and keeps re-explaining the same conventions. The README lists four failure modes it claims to fix: the agent forgets coding style, onboarding a new codebase means guessing at architecture, switching IDEs means different rules everywhere, and asking how something works means reading random files. Those are all context problems, not model problems, which is why the project ships as files plus a Q&A engine rather than as another plugin.

Worth noting: the README carries a promotional block for a third-party router, described by the author as not an advertisement but a personal recommendation. That is the maintainer's own disclosure and it sits above the install instructions. Read it as you would any affiliate-style recommendation in a README.

How the .repobrain knowledge layer and ModuleAgents fit together

The mechanism has two halves. First, rb-refresh deploys what the README calls a multi-agent cluster: each module gets its own Agent that reads the source and generates a knowledge document. Those documents land in a .repobrain/ folder, alongside project-level files the README names as conventions.md, module_registry.md, map.md and structure.md. Second, rb-ask routes a question to the ModuleAgent responsible for the relevant area, and the answer is grounded in real code with file paths and line numbers.

Routing is the part that matters. A question about authentication should not be answered by an agent that has only read the billing module, and the registry file is what makes that mapping possible. The README describes the architecture as files plus a live Q&A engine rather than plugins, which is why the same .repobrain/ folder is readable from every supported host. There is also an MCP surface: the Dockerfile's CMD runs rb-mcp --workspace /app, so the knowledge hub can be exposed as an MCP server against a mounted workspace.

The benchmark section adds two engine details that explain earlier gaps. The function _ask_with_agent_md now surfaces project-level docs into its answer prompts, which the README says removed a refusal pattern where module knowledge did not include project-wide conventions. And the structured-facts answer agents now have search_code, read_file, list_directory, read_file_metadata and search_by_type bound at runtime, so the model can read actual source instead of paraphrasing the knowledge graph. Those are the kind of fixes that tell you where the design was thin.

Installing RepoBrain in Claude Code and running a first question

The recommended path is the plugin marketplace. The README gives these commands, and the rb CLI plus engine are described as auto-installing together on Claude's first session. The first block adds the marketplace and installs the plugin; the second configures a backend and builds the knowledge base before you ask anything.

/plugin marketplace add study8677/repobrain
/plugin install repobrain@repobrain

After the plugin is in place, rb-setup runs interactively and writes .env, choosing either a logged-in local CLI or a pasted API key. rb-refresh then creates .repobrain/ on its first run.

/repobrain:rb-setup
/repobrain:rb-refresh
/repobrain:rb-ask "How does auth work?"

The answer you should see is grounded in real code with file paths and line numbers rather than a paraphrase. If the knowledge folder is empty, the refresh step did not complete, and the README does not describe a partial-refresh state.

Installing the engine manually for Codex CLI

Codex CLI does not support the plugin hooks yet, so the README calls for a manual engine install through pipx. Codex auto-discovers slash commands from the plugin's commands/ directory, which means the same four commands work there without the repobrain: namespace prefix.

pipx install "git+https://github.com/study8677/repobrain.git#subdirectory=engine"

Note that the engine installs from a git URL with a subdirectory fragment rather than from a package index. That means an upgrade follows the default branch unless you pin a commit, and the repository's VERSIONING.md is the file to read before deciding how tightly to pin.

Running RepoBrain as a container with docker-compose

The repository ships a Dockerfile and a docker-compose.yml, so there is a third path that does not touch your local Python environment. The compose file defines a single agent service built from the repository root, with .env marked optional, and it passes OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL, GOOGLE_API_KEY, GEMINI_MODEL_NAME, AGENT_NAME and DEBUG_MODE into the container. Three volumes are mounted: ./memory, ./artifacts and ./.repobrain, which is what makes the knowledge folder persist across restarts. The restart policy is unless-stopped.

The Dockerfile is a two-stage build on python:3.12-slim. The builder stage copies engine/ and runs pip install --user --no-cache-dir ./engine. The runtime stage creates an unprivileged user with UID 10001, copies the installed packages into that user's home, copies the rest of the application, and runs rb-mcp --workspace /app. Two consequences follow. The container runs as a non-root user, which is the right default. And the workspace it answers about is whatever you mount at /app, so a misconfigured volume means it will confidently answer questions about the wrong tree.

Where RepoBrain is the wrong tool

The benchmark table is the most honest part of the README, and it is also where the limits show. On 12 synthesis questions covering project and architecture tours, RepoBrain scored 116/144 (81%) against Codex CLI's 144/144 and Claude Code's 136/144. That is a 23-point gap on exactly the category a new contributor cares about most. The README does not explain the cause, and the report is linked rather than summarized, so treat architecture-level questions as a known weak spot until you have checked the artifacts/benchmark-2026-05-09/REPORT.md numbers against your own repository.

Latency is the second constraint. The same table gives a mean of 160 seconds per audit question for RepoBrain, against 100 seconds for Claude Code. Factual lookups are fast at 56 seconds, but audit work is slow. If your workflow is a tight edit-test loop, a two-and-a-half-minute wait per question is a different product from what you expected.

Third, the knowledge is only as fresh as the last refresh. The README describes rb-refresh as the step that creates and updates .repobrain/, and nothing in it suggests continuous re-indexing. Between refreshes the agents are answering from a snapshot. On a branch with heavy churn, that snapshot can be wrong in ways that look like confident answers. The README does not document rollback either, so there is no described path for undoing a refresh that produced bad knowledge.

RepoBrain against handing the agent a CLAUDE.md

The realistic alternative is not another knowledge engine. It is the thing most teams already do: write a CLAUDE.md or AGENTS.md and let the agent read the repository itself. The difference in approach is where the reading happens. With a documentation file, the agent reads once at the start of a session and then works from memory plus whatever files it opens. With RepoBrain, the reading happened earlier, per module, and the question is routed to the agent that already holds that module's context.

That trade is real in both directions. The documentation file costs nothing to maintain and is trivially reviewable in a pull request. The .repobrain folder requires a refresh cycle, and the quality of its contents depends on the ModuleAgents having read the right files. The benchmark's factual band shows the two approaches converging: 179/180 for RepoBrain against 179/180 for Codex CLI on factual lookups. The separation appears on synthesis, where the plain agent wins in this evaluation. So the honest framing is that RepoBrain buys routing and portability across IDEs, and it does not currently buy better architecture explanations.

Maintenance, licensing and the upgrade surface

The repository is not archived, and the most recent push was on 2026-07-10, which is when v0.3.1 was tagged. The release history shows a rename in flight: v0.2.1 shipped as Antigravity 0.2.1, while v0.3.0 and v0.3.1 shipped as RepoBrain. The README confirms the project was formerly known as Antigravity Workspace Template. If you pinned anything against the old name, that rename is the upgrade cost to plan for, and there is a VERSIONING.md in the repository root that presumably covers the policy.

The licence is MIT. That is permissive, and it means you can vendor the engine and the .repobrain output into a private repository without a copyleft obligation. It also means there is no warranty, and the README's own benchmark caveats are the only quality signal you get. Nothing here suggests the project offers commercial support. This is a description of the licence terms, not legal advice; if the generated knowledge documents quote third-party source, that is a question for your own counsel.

The engine installs from a git URL with a subdirectory fragment rather than from PyPI, per the pipx command in the README. That is worth weighing: upgrades track the default branch unless you pin a commit, and the repository's own VERSIONING.md is the file to read before you decide how tightly to pin.

Editorial conclusion

Adopt RepoBrain if your team already works inside Claude Code, Codex CLI, Cursor or Windsurf and wants one .repobrain folder that every host reads, with answers tied to file paths and line numbers. Skip it if you need a hosted service with an audit trail, or if your repository is small enough that a single CLAUDE.md is cheaper to maintain than a refresh cycle. Before committing, run /repobrain:rb-setup, then /repobrain:rb-refresh on one module and open .repobrain/conventions.md to judge whether the generated knowledge matches how your team actually writes code. The README does not document rollback, so decide how you will remove .repobrain and the engine package if the answers disappoint.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes