<div align="center"> <img src="docs/assets/logo.svg" alt="RepoBrain" width="140"/>

RepoBrain

Give your repo a brain 🧠 — ChatGPT for your codebase, works in Claude Code, Cursor, Codex, Windsurf & 4 more.

_{Formerly known as <b>Antigravity Workspace Template</b> — same project, new name.}

<br/> <img src="https://img.shields.io/badge/Claude_Code-✓-D97757?style=flat-square" alt="Claude Code"/> <img src="https://img.shields.io/badge/Codex_CLI-✓-412991?style=flat-square" alt="Codex"/> <img src="https://img.shields.io/badge/Cursor-✓-000000?style=flat-square" alt="Cursor"/> <img src="https://img.shields.io/badge/Windsurf-✓-06B6D4?style=flat-square" alt="Windsurf"/> <img src="https://img.shields.io/badge/Gemini_CLI-✓-4285F4?style=flat-square" alt="Gemini CLI"/> <img src="https://img.shields.io/badge/VS_Code_+_Copilot-✓-007ACC?style=flat-square" alt="VS Code"/> <img src="https://img.shields.io/badge/Cline-✓-FF6B6B?style=flat-square" alt="Cline"/> <img src="https://img.shields.io/badge/Aider-✓-8B5CF6?style=flat-square" alt="Aider"/>

_{English · 中文 · Español}

<br/><br/>

<img src="docs/assets/demo.gif" alt="rb-ask demo — ask your codebase, get grounded answers with file paths and line numbers" width="800"/> </div> <br/> <div align="center"> <p><strong>🚀 实测推荐:</strong> <a href="https://teamorouter.com/?i=e188641773">TeamoRouter</a> —— 非广告，我自己在 Codex、Claude Code 等 AI 编程工具里高强度使用：一个 API Key 接入 Claude、GPT-5.5 等，模型价格方便调整，价格优惠，并没有掺水的情况。接入指南见 <a href="https://github.com/xixiaoyao/openrouter-api-key">openrouter-api-key</a>。</p> </div> <br/> <div align="center"> <img src="docs/assets/before_after.svg" alt="Before vs After RepoBrain" width="800"/> </div> <br/>

# 1 — Install (Claude Code plugin marketplace)
/plugin marketplace add study8677/repobrain
/plugin install repobrain@repobrain

# 2 — Pick LLM provider, build the knowledge base
/repobrain:rb-setup
/repobrain:rb-refresh

# 3 — Ask anything, grounded in real code with file paths + line numbers
/repobrain:rb-ask "How does auth work?"

99% factual · 2.1× faster than Codex CLI · works in any AI IDE. Head-to-head benchmark ↓ Codex CLI users — drop the repobrain: prefix; the same four slash commands ship there too.

---

Why RepoBrain?

Cross-IDE repository knowledge engine for grounded codebase Q&A. Same .repobrain/ knowledge layer reads in every IDE; one engine, every host.

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

<details> <summary><b>Four concrete failure modes RepoBrain fixes</b> — click to expand</summary>

| Problem | Without RepoBrain | With RepoBrain | |:--------|:-------------------|:-----------------| | Agent forgets coding style | Repeats the same corrections | Reads .repobrain/conventions.md — gets it right the first time | | Onboarding a new codebase | Agent guesses at architecture | rb-refresh → ModuleAgents self-learn each module | | Switching between IDEs | Different rules everywhere | One .repobrain/ folder — every IDE reads it | | Asking "how does X work?" | Agent reads random files | ask_project MCP → Router routes to the responsible ModuleAgent |

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

</details>

---

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).

| Question type | RepoBrain | Codex CLI | Claude Code | |:---|:---:|:---:|:---:| | 15 factual lookups | 179/180 (99%) | 179/180 (99%) | 178/180 (99%) | | 12 synthesis (project / arch tour) | 116/144 (81%) | 144/144 (100%) | 136/144 (94%) | | 9 audit / security | 105/108 (97%) | 104/108 (96%) | 98/108 (91%) |

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):

| Question type | RepoBrain | Codex | Claude | |:---|:---:|:---:|:---:| | Factual | 56s | 119s | 42s | | Audit | 160s | 177s | 100s |

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.

<details> <summary><b>What changed in this repo to get there</b> — engine fixes that drove the numbers</summary>

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.

</details>

---

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.

<details> <summary><b>Option B — Manual install: engine + CLI via pip</b></summary>

# 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)

</details> <details> <summary><b>Option C — Context files only (any IDE, no LLM needed)</b></summary>

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/

</details>

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.

| Claude Code | Codex CLI | Purpose | |---|---|---| | /repobrain:rb-setup | /rb-setup | First-time setup — pick LLM provider, write .env | | /repobrain:rb-refresh [quick] | /rb-refresh [quick] | Build / incrementally refresh the project knowledge base | | /repobrain:rb-ask <question> | /rb-ask <question> | Routed Q&A on the current codebase | | /repobrain:rb-init <name> | /rb-init <name> | Scaffold a new multi-agent repo from this template |

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

<details> <summary><b>What each slash command actually does</b></summary>

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