An AI Agent's capability ceiling = the quality of context it can read.

rb-refresh deploys a multi-agent cluster that autonomously reads your code — each module gets its own Agent that generates a knowledge doc. rb-ask routes questions to the right Agent, grounded in real code with file paths and line numbers.

Instead of handing Claude Code / Codex a repo-wide grep and making it hunt on its own, give it a ChatGPT for your repository.

Traditional approach:              RepoBrain approach:
  CLAUDE.md = 5000 lines of docs     Claude Code calls ask_project("how does auth work?")
  Agent reads it all, forgets most   Router → ModuleAgent reads actual source, returns exact answer
  Hallucination rate stays high      Grounded in real code, file paths, and git history

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

Head-to-Head Eval: RepoBrain vs Codex CLI vs Claude Code (2026-05-09)

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.

Quick Start

Plugin install for Claude Code / Codex CLI (recommended — the rb CLI and engine auto-install together on Claude's first session):

# 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"
pipx inject --force --include-apps repobrain-engine "git+https://github.com/study8677/repobrain.git#subdirectory=cli"
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.

Slash Commands

Same four slash commands ship to both Claude Code and Codex CLI. Claude namespaces them as /repobrain:<name>; Codex auto-discovers commands/ and surfaces the bare /<name> form. No retraining — same flow on both hosts.

A typical first session is rb-setup → rb-refresh → rb-ask. If installation or provider setup looks wrong, run rb doctor --workspace ..

rb-setup — first-time configuration

Run this once per project, right after installing the plugin. Interactive picker for the LLM provider (OpenAI / DeepSeek / Groq / 阿里灵积 / NVIDIA NIM / Ollama local / any OpenAI-compatible endpoint), then writes .env to the project root with OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL, RB_ASK_TIMEOUT_SECONDS. It can also write an explicit local Codex host-runner config for experimental no-API-key rb-ask. Also ensures .env is in .gitignore. Skip it if you already have a working .env.

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 answe