repobrain

Shows active maintenance signals

Plugin install for Claude Code / Codex CLI (recommended — the engine CLI auto-installs on first session via SessionStart hook):

# Claude Code
/plugin marketplace add study8677/repobrain
/plugin install repobrain@repobrain
/repobrain:rb-setup            # interactive: pick LLM provider, paste API key, writes .env
/repobrain:rb-refresh          # first refresh auto-creates .repobrain/
/repobrain:rb-ask "How does this project work?"

# Codex CLI (manual engine install — Codex hooks are not yet supported)
pipx install "git+https://github.com/study8677/repobrain.git#subdirectory=engine"
codex plugin marketplace add study8677/repobrain
/rb-setup
/rb-refresh
/rb-ask "How does this project work?"

Codex auto-discovers slash commands from the plugin's commands/ directory, so the same four commands work without the repobrain: namespace prefix. The raw CLI calls (rb-refresh --workspace ., rb-ask "..." --workspace .) also still work. If your Codex build supports MCP, register rb-mcp --workspace <project> separately.

# 1. Install engine + CLI
pip install "git+https://github.com/study8677/repobrain.git#subdirectory=cli"
pip install "git+https://github.com/study8677/repobrain.git#subdirectory=engine"

# 2. Configure .env with any OpenAI-compatible API key
cd my-project
cat > .env <<EOF
OPENAI_BASE_URL=https://your-endpoint/v1
OPENAI_API_KEY=your-key
OPENAI_MODEL=your-model
RB_ASK_TIMEOUT_SECONDS=120
EOF

# 3. Build knowledge base (ModuleAgents self-learn each module)
rb-refresh --workspace .

# 4. Ask anything
rb-ask "How does auth work in this project?"

# 5. (Optional) Register as MCP server for Claude Code
claude mcp add repobrain rb-mcp -- --workspace $(pwd)

pip install git+https://github.com/study8677/repobrain.git#subdirectory=cli
rb init my-project && cd my-project
# IDE entry files bootstrap into AGENTS.md; dynamic knowledge is in .repobrain/

See INSTALL.md for full details and troubleshooting.

Asymmetric benchmark on three real-world Python codebases — fastapi/fastapi, psf/requests, fastapi/sqlmodel — asking each tool the same 36 questions across three difficulty bands. All three tools used gpt-5.5 with high reasoning effort; Codex and Claude had full read access to the workspace. Codex was the grader (4-axis 0–3 rubric, scores verified against actual source).

Combined factual + audit (24 cells): RepoBrain 284/288, Codex 283/288, Claude 276/288. RepoBrain edges out both — at lower latency than Codex on every single question.

Latency (mean wall-clock per question, same proxy):

RepoBrain is 2.1× faster than Codex on factual and on par with Codex on audit, while matching or beating it on correctness. Claude is fastest on audit but loses 7 percentage points of correctness.

Two engine fixes landed during the benchmark, both committed in this branch:

1. _ask_with_agent_md now surfaces project-level docs (conventions.md, module_registry.md, map.md, structure.md) into its answer prompts. Removes the "module knowledge does not include project-wide conventions" refusal pattern.
2. The structured-facts answer agents now have search_code, read_file, list_directory, read_file_metadata, search_by_type bound at runtime, so the LLM can grep and read actual source instead of paraphrasing the KG.

Full report (data, methodology, per-cell tables, caveats): artifacts/benchmark-2026-05-09/REPORT.md.

rb-refresh — build / refresh the knowledge base

Deploys the multi-agent cluster to read your code: each module gets its own Agent that produces a knowledge doc under .repobrain/agents/*.md, plus a map.md routing index. Run after install, after significant code changes, or when rb-ask returns stale answers. The first refresh auto-creates .repobrain/ — no separate init step needed. Pass quick for an incremental update, failed-only to rerun only previously failed modules.

Time: a few minutes for small repos, longer for large ones. Requires rb-setup to have completed. Full LLM refresh requires an API-key/OpenAI-compatible provider; local host-runner mode can use RB_REFRESH_SCAN_ONLY=1 rb-refresh --workspace . for scan artifacts.

rb-ask — routed Q&A on the codebase

The main reason this plugin exists. Routes your question to the right ModuleAgent (and GitAgent when applicable), then returns an answer grounded in actual source with file paths and line numbers. Use it before manually grepping or reading files — it's faster and more accurate. Good question shapes: "where is X defined/handled?", "why was Y done this way?", "how does the auth flow work?", "what depends on module Z?".

Requires a knowledge base — if you see "no index" or empty answers, run rb-refresh first.

rb-init — scaffold a new multi-agent repo

Creates a new project from the RepoBrain template. Two modes: quick (fast scaffold, clean copy) and full (adds runtime profile, .env, mission file, sandbox config, optional git init). This is for starting a new repo — you do not need it before rb-refresh on an existing project.

The plugin also bundles the agent-repo-init skill (the same backend that rb-init invokes — Codex / Claude can also match it by description) and the optional rb-mcp MCP server (ask_project + refresh_project) for tool-style integration.

Architecture is files + a live Q&A engine, not plugins. Portable across any IDE, any LLM, zero vendor lock-in.