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

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

rb-setup — first-time configuration

Run this once per project, right after installing the plugin. Interactive picker that first detects the headless CLIs you're already logged into (Codex / Trae / Claude / Gemini) and offers a no-API-key local host-runner as the most convenient option — no key to paste, RepoBrain just drives your existing CLI login for both rb-ask and rb-refresh. If you'd rather use a hosted model, it also offers the API-key providers (OpenAI / DeepSeek / Groq / 阿里灵积 / NVIDIA NIM / Ollama local / any OpenAI-compatible endpoint). Either way it writes .env to the project root — RB_HOST_RUNNER + RB_HOST_COMMAND for a local CLI, or OPENAI_BASE_URL / OPENAI_API_KEY / OPENAI_MODEL for a provider — and 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 and creates an atomic generation baseline. The first run must be a full refresh. Later, quick compares committed changes from the active generation to HEAD, requires a clean worktree, and lets RepoBrain's ImpactPlanner plus an independent Verifier execute only affected Agent groups. It never falls back to a full refresh. Use failed-only to resume failed or pending groups for the same target commit. rb-ask only warns about new commits; it never refreshes knowledge automatically.

Time: a few minutes for small repos, longer for large ones. Requires rb-setup to have completed. Works with either backend: an API-key/OpenAI-compatible provider runs the full LLM refresh, while a local host-runner (Codex / Trae / Claude / …) runs the tool-free stages (module docs, map.md) through your logged-in CLI and automatically degrades the tool/handoff stages (conventions, git insights) to deterministic output — no API key needed. Add RB_REFRESH_SCAN_ONLY=1 only if you want a fast structure-only index with no LLM narration at all.

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.

Calling from another AI / script? Add --json for a stable, parseable envelope instead of human-formatted text — this is the lightweight way to let any agent that can run a shell command query RepoBrain, no MCP server required:

rb-ask "How does auth work?" --workspace . --json
# → {"answer": "...", "sources": [...], "limitations": [...], "workspace": "...", "question": "..."}

On failure, --json keeps stdout empty and writes {"error": "..."} to stderr with a non-zero exit code, so a calling agent can branch cleanly. It runs the same engine as everything else, so it works with an API-key provider or a no-API-key local host runner. See Let another AI call RepoBrain (CLI, no MCP).

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.

rb-refresh — Multi-agent self-learning (8-step pipeline)

rb-refresh --workspace my-project

1. Scan codebase (languages, frameworks, structure)
2. Multi-agent pipeline generates conventions.md
3. Generate structure.md — language-agnostic file tree with line counts
4. Build knowledge graph (knowledge_graph.json + mermaid)
5. Write document/data/media indexes
6. LLM full-context analysis — group files by import graph + directory + prefix, pre-load into context (~30K tokens per sub-agent), filter out build artifacts. Each sub-agent reads the full source code and outputs a comprehensive Markdown knowledge document (agents/*.md). Large modules get multiple agent docs (one per group, no merging). Global API concurrency control prevents rate-limiting. Fully language-agnostic — works with any programming language.
7. RefreshGitAgent analyzes git history, generates _git_insights.md
8. Map Agent reads all agent docs → generates map.md (module routing index with descriptions and key topics)

rb-ask — Router-based Q&A

rb-ask "How does auth work in this project?"

Router reads map.md → selects modules → reads agents/*.md → LLM answers with code references. Multiple agent docs are read in parallel, then a Synthesizer combines answers.

Falls back to the legacy Router → ModuleAgent/GitAgent swarm when agent docs are not yet generated.

Key design choices

• LLM as analyzer: No AST parsing or regex — source code is fed directly to LLMs. Works with any programming language out of the box.
• Smart grouping: Files grouped by import relationships, directory co-location, filename prefixes. Build artifacts filtered. Hard character limit (800K) prevents context overflow.
• No information loss: Large modules produce multiple agent.md files — no merging or compression. Parallel reads + Synthesizer recombines at answer time.
• Global API concurrency control: RB_API_CONCURRENCY limits total simultaneous LLM calls.
• Language-agnostic module detection: Pure directory structure — no __init__.py or any language-specific marker required.

Instead of reading hundreds of documentation files, Claude Code can call ask_project as a live tool — backed by a dynamic multi-agent cluster: Router routes questions to the right ModuleAgent, returning grounded answers with file paths and line numbers.

Setup:

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

# Refresh knowledge base first (ModuleAgents self-learn each module)
rb-refresh --workspace /path/to/project

# Register as MCP server in Claude Code
claude mcp add repobrain rb-mcp -- --workspace /path/to/project

Tools exposed to Claude Code:

MCPClientManager lets your agents connect to external MCP servers (GitHub, databases, etc.), auto-discovering and registering tools.

// mcp_servers.json
{
  "servers": [
    {
      "name": "github",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "enabled": true
    }
  ]
}

Set MCP_ENABLED=true in .env to make configured servers available, and set RB_ALLOW_MCP=true only when you want rb-ask to auto-connect those external servers. Stdio MCP servers inherit process environment plus configured env values, so treat enabled servers as local-permission code.

The default sandbox is for trusted local workspaces, not untrusted code isolation. Retrieval graph files redact common secrets before writing to disk, but full mode can still preserve source snippets. See Sandbox docs.

rb ask / rb refresh are available when both cli/ and engine/ are installed. rb-ask / rb-refresh