RepoBrain

Motor de conocimiento de repositorios, portable entre IDEs, para Q&A de codebases con evidencia.

_{Anteriormente conocido como Antigravity Workspace Template — el mismo proyecto, nuevo nombre.}

rb-refresh construye la capa de conocimiento portable; rb-ask enruta preguntas al contexto de módulo correcto y responde con evidencia de código. Plugins, CLI y MCP son canales de entrega alrededor de ese flujo.

Idioma: English | 中文 | Español

El techo de capacidad de un AI Agent = la calidad del contexto que puede leer.

El motor es el núcleo: rb-refresh despliega un clúster multi-agente que lee tu código autónomamente — cada módulo obtiene su propio Agent que genera documentación de conocimiento. rb-ask enruta preguntas al Agent correcto, con respuestas basadas en código real con rutas de archivo y números de línea.

En vez de darle a Claude Code / Codex un grep del repositorio para que busque por su cuenta, dale un ChatGPT para tu repositorio.

Resultados principales en cuatro repositorios: 95.83% de precisión semántica ponderada y consultas puntuadas 4.04× más rápidas que CodeGraph + Trae. Ver resultados.

Enfoque tradicional:                    Enfoque RepoBrain:
  CLAUDE.md = 5000 líneas de docs         Claude Code llama ask_project("¿cómo funciona auth?")
  El agente lee todo, olvida la mitad     Router → ModuleAgent lee código real, devuelve respuesta exacta
  La tasa de alucinación sigue alta       Fundamentado en código real, rutas de archivo y git

La arquitectura son archivos + un motor Q&A en vivo, no plugins. Portable entre cualquier IDE, cualquier LLM, cero lock-in.

Los mismos cuatro comandos slash funcionan tanto en Claude Code como en Codex CLI. Claude los expone con el espacio de nombres /repobrain:<nombre>; Codex auto-descubre el directorio commands/ y los presenta sin prefijo, como /<nombre>. Mismo flujo en ambos hosts — sin reaprender.

Sesión típica inicial: rb-setup → rb-refresh → rb-ask. Detalles abajo.

Ejecútalo una vez por proyecto, justo después de instalar el plugin. Selector interactivo del proveedor LLM (OpenAI / DeepSeek / Groq / 阿里灵积 / NVIDIA NIM / Ollama local / cualquier endpoint OpenAI-compatible), luego escribe .env en la raíz del proyecto con OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL, RB_ASK_TIMEOUT_SECONDS. También asegura que .env esté en .gitignore. Sáltatelo si ya tienes un .env funcional.

# Claude Code
/repobrain:rb-setup

# Codex CLI
/rb-setup

El primer refresh debe ser completo para crear una generación base. Después, quick compara solo commits, exige un worktree limpio y usa ImpactPlanner más un Verifier independiente para ejecutar únicamente los grupos Agent afectados. Nunca cambia automáticamente a refresh completo. failed-only reanuda los grupos fallidos o pendientes del mismo commit. rb-ask solo avisa de commits nuevos y nunca actualiza la base automáticamente.

# Claude Code
/repobrain:rb-refresh
/repobrain:rb-refresh quick

# Codex CLI
/rb-refresh
/rb-refresh quick

Tiempo: pocos minutos en repos pequeños, más en repos grandes. Requiere rb-setup ya completado.

La razón principal por la que existe este plugin. Enruta tu pregunta al ModuleAgent adecuado (y a GitAgent cuando aplica), y devuelve una respuesta fundamentada en el código real, con rutas de archivo y números de línea. Úsalo antes de hacer grep manual o leer archivos — es más rápido y más preciso. Buenas formas de pregunta: "¿dónde se define/maneja X?", "¿por qué se hizo Y de esta forma?", "¿cómo funciona el flujo de auth?", "¿qué depende del módulo Z?".

# Claude Code
/repobrain:rb-ask "¿Cómo funciona la autenticación?"

# Codex CLI
/rb-ask "¿Cómo funciona la autenticación?"

Requiere una base de conocimiento — si ves "sin índice" o respuestas vacías, ejecuta rb-refresh primero.

Crea un nuevo proyecto desde la plantilla RepoBrain. Dos modos: quick (andamio rápido, copia limpia) y full (añade runtime profile, .env, archivo de misión, config de sandbox, git init opcional). Es para empezar un repo nuevo — no lo necesitas antes de rb-refresh en un proyecto existente.

# Claude Code
/repobrain:rb-init my-agent
/repobrain:rb-init my-agent full

# Codex CLI
/rb-init my-agent
/rb-init my-agent full

El plugin también incluye el skill agent-repo-init (es el backend que rb-init invoca — Codex / Claude también lo emparejan por descripción) y el servidor MCP opcional rb-mcp (ask_project + refresh_project) para integración tipo herramienta.

Opción A — Instalación de una línea como plugin de Claude Code / Codex CLI (recomendado)

# Claude Code (auto-instala juntos el CLI rb y el motor Python vía SessionStart)
/plugin marketplace add study8677/repobrain
/plugin install repobrain@repobrain
/repobrain:rb-setup            # interactivo: elige proveedor LLM, pega API key, escribe .env
/repobrain:rb-refresh          # el primer refresh crea .repobrain/ automáticamente
/repobrain:rb-ask "¿Cómo funciona este proyecto?"

# Codex CLI (instala el motor manualmente primero; los hooks de Codex aún no son soportados)
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                        # mismos comandos en Codex, sin el prefijo repobrain:
/rb-refresh
/rb-ask "¿Cómo funciona este proyecto?"

Codex CLI auto-descubre los comandos slash desde el directorio commands/ del plugin, así que los mismos cuatro comandos están disponibles sin el prefijo repobrain: (/rb-setup, /rb-refresh, /rb-ask, /rb-init). También puedes seguir usando el CLI directo (rb-refresh --workspace ., rb-ask "..." --workspace .) y diagnosticar la instalación con rb doctor --workspace ..

Si la sesión actual de Claude Code dice que la herramienta MCP de RepoBrain no está conectada, reinicia Claude Code una vez y vuelve a ejecutar /repobrain:rb-refresh. Es un problema de carga de sesión, no de API key. Consulta troubleshooting.

Después de instalar y configurar dispondrás de los comandos slash rb-ask <pregunta>, rb-refresh, rb-init <nombre> en ambos hosts, y del servidor MCP repobrain (ask_project + refresh_project). Ver INSTALL.md para detalles de instalación y troubleshooting.

Opción B — Instalación manual: motor + CLI vía pip

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

# 2. Configurar .env (cualquier API compatible con OpenAI)
cd mi-proyecto
cat > .env <<EOF
OPENAI_BASE_URL=https://tu-endpoint/v1
OPENAI_API_KEY=tu-key
OPENAI_MODEL=tu-modelo
RB_ASK_TIMEOUT_SECONDS=120
EOF

# 3. Construir base de conocimiento (ModuleAgents aprenden cada módulo)
rb-refresh --workspace .

# 4. Preguntar
rb-ask "¿Cómo funciona la autenticación en este proyecto?"

# 5. (Opcional) Registrar como servidor MCP para Claude Code
claude mcp add repobrain rb-mcp -- --workspace $(pwd)

Opción C — Solo archivos de contexto (cualquier IDE, sin LLM)

pip install git+https://github.com/study8677/repobrain.git#subdirectory=cli
rb init mi-proyecto && cd mi-proyecto
# Los archivos de entrada del IDE hacen bootstrap hacia AGENTS.md; el contexto dinámico vive en .repobrain/

  rb init             Inyectar archivos de contexto (--force para sobrescribir)
       │
       ▼
  .repobrain/       Base de conocimiento compartida — cada IDE lee de aquí
       │
       ├──► rb-refresh     Aprendizaje multi-agente dinámico → docs de conocimiento + mapa estructural
       ├──► rb-ask         Router → ModuleAgent Q&A con evidencia de código en vivo
       └──► rb-mcp         Servidor MCP → Claude Code llama directamente

Clúster Multi-Agente Dinámico — Durante rb-refresh, el motor usa agrupación funcional inteligente: archivos agrupados por relaciones de import, co-ubicación en directorios y prefijos de nombre. El código fuente se pre-carga directamente en el contexto del agente (sin tool calls), y los artefactos de build se filtran automáticamente. Cada sub-agente analiza ~30K tokens de código enfocado en 1 llamada LLM y produce un documento de conocimiento Markdown completo (agents/*.md). Módulos grandes generan múltiples agent docs en paralelo (uno por grupo, sin fusión ni pérdida de información). Un Map Agent lee todos los docs y genera map.md — un índice de enrutamiento. Durante rb-ask, Router lee map.md para seleccionar módulos relevantes, luego alimenta sus agent docs a los agentes de respuesta. Completamente agnóstico al lenguaje — detección de módulos por estructura de directorios pura, análisis de código realizado íntegramente por LLMs. Funciona con cualquier lenguaje de programación.

GitAgent — Un agente dedicado a analizar el historial git — entiende quién cambió qué y por qué.

Feedback de auditoría NLPM — Este repositorio se ha beneficiado de NLPM, un linter de programación en lenguaje natural para plugins de Claude Code, skills y definiciones de agentes creado por xiaolai. Su auditoría ayudó a encontrar mejoras útiles en frontmatter de skills e higiene de dependencias.

rb ask / rb refresh están disponibles cuando cli/ y engine/ están instalados. rb-ask / rb-refresh son los entrypoints disponibles con solo el engine.

repobrain/
├── cli/                     # rb CLI — ligero, instalable con pip
│   └── templates/           # .cursorrules, CLAUDE.md, .repobrain/, ...
└── engine/                  # Motor multi-agente + Knowledge Hub
    └── repobrain_engine/
        ├── _cli_entry.py    # rb-ask / rb-refresh puntos de entrada
        ├── config.py        # Configuración Pydantic
        ├── hub/             # ★ Núcleo: clúster multi-agente
        │   ├── agents.py    #   Refresh swarm (ScanAnalyst → ArchitectureReviewer → ConventionWriter) + Ask swarm (Router / ModuleAgent / GitAgent)
        │   ├── contracts.py #   Modelos Pydantic: claims, evidencia, estado de refresh
        │   ├── ask_pipeline.py    # facts estructurados + swarm legacy
        │   ├── refresh_pipeline.py # orquestación de refresh basado en evidencia
        │   ├── ask_tools.py #   Exploración de código
        │   ├── scanner.py   #   Escaneo multi-lenguaje de proyecto
        │   ├── module_grouping.py # agrupación funcional inteligente
        │   ├── incremental.py #   committed-diff / --quick agent-group refresh
        │   ├── host_runner.py #   local CLI backend, no API key
        │   ├── storage.py   #   generation dirs + current.json
        │   ├── mcp_server.py#   Servidor MCP (rb-mcp)
        │   └── language_adapters/ # adaptadores específicos de lenguaje
        ├── mcp_client.py    # Consumidor MCP (conecta herramientas externas)
        ├── memory.py        # Memoria de interacción persistente
        ├── tools/           # Herramientas MCP + extensiones
        ├── skills/          # Cargador de habilidades
        └── sandbox/         # Ejecución de código (local / microsandbox)

CLI (pip install .../cli) — Cero deps de LLM. Inyecta plantillas, registra reportes y decisiones offline.

Engine (pip install .../engine) — Runtime de conocimiento del repositorio. Alimenta rb-ask, rb-refresh, rb-mcp. Usa el endpoint OpenAI-compatible escrito por rb-setup (OpenAI, DeepSeek, Groq, DashScope, NVIDIA NIM, Ollama o personalizado).

Nuevas actualizaciones de empaquetado de skills:

• engine/repobrain_engine/skills/graph-retrieval/ — herramientas de recuperación orientadas a grafo para razonamiento de estructura y rutas de llamadas.
• engine/repobrain_engine/skills/knowledge-layer/ — herramientas de capa de conocimiento para consolidación de contexto semántico del proyecto.

# Instalar ambos para la experiencia completa
pip install "git+https://...#subdirectory=cli"
pip install "git+https://...#subdirectory=engine"

rb init mi-proyecto
# ¿Ya inicializado? Usa --force para sobrescribir:
rb init mi-proyecto --force

Crea AGENTS.md (reglas de comportamiento autoritativas), archivos bootstrap de IDE (.cursorrules, CLAUDE.md, .windsurfrules, .clinerules, .github/copilot-instructions.md) y archivos de contexto dinámico en .repobrain/.

rb-refresh --workspace mi-proyecto

Pipeline de 8 pasos:

1. Escanear codebase (lenguajes, frameworks, estructura)
2. Pipeline multi-agente genera conventions.md
3. Generar structure.md — árbol de archivos agnóstico al lenguaje con conteos de líneas
4. Construir grafo de conocimiento (knowledge_graph.json + mermaid)
5. Escribir índices de documentos/datos/media
6. Análisis completo por LLM — archivos agrupados por grafo de imports + directorio + prefijo, pre-cargados en contexto (~30K tokens por sub-agente), artefactos de build filtrados automáticamente. Cada sub-agente lee el código fuente completo y produce un documento de conocimiento Markdown completo (agents/*.md). Módulos grandes generan múltiples agent docs (uno por grupo, sin fusión). Control global de concurrencia API previene rate-limiting. Completamente agnóstico al lenguaje — funciona con cualquier lenguaje de programación.
7. RefreshGitAgent analiza historial git, genera _git_insights.md
8. Map Agent lee todos los agent docs → genera map.md (índice de enrutamiento de módulos con descripciones y temas clave)

rb-ask "¿Cómo funciona la autenticación en este proyecto?"

El pipeline de ask usa una vía semántica: Router lee map.md → selecciona módulos → lee agents/*.md → LLM responde con referencias al código. Múltiples agent docs se leen en paralelo, luego un Synthesizer combina las respuestas.

Si los agent docs aún no se han generado, recurre al swarm legacy Router → ModuleAgent/GitAgent.

La arquitectura está codificada en archivos — cualquier agente que lea archivos del proyecto se beneficia:

Todo se genera con rb init: AGENTS.md es el único rulebook de comportamiento, los archivos específicos por IDE son bootstraps ligeros, y .repobrain/ guarda el contexto dinámico compartido del proyecto.

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

# Refrescar base de conocimiento primero (ModuleAgents aprenden cada módulo)
rb-refresh --workspace /ruta/al/proyecto

# Registrar como servidor MCP en Claude Code
claude mcp add repobrain rb-mcp -- --workspace /ruta/al/proyecto

 rb-refresh:                                 rb-ask:

 Para cada módulo:                           Router (lee map.md)
 ┌ Agrupar archivos por grafo de imports       └── leer agents/*.md → respuesta LLM
 ├ Pre-cargar ~30K tokens por sub-agente
 ├ Filtrar artefactos de build
 ├ Sub-agentes → documentos Markdown agent
 ├ agents/{module}.md (o /group_N.md)
 └ Map Agent → map.md

# ModuleAgents aprenden tu codebase
rb-refresh

# Solo escanear archivos cambiados desde el último refresh
rb-refresh --quick

# Router enruta inteligentemente al ModuleAgent correcto
rb-ask "¿Qué patrones de testing usa este proyecto?"

# Registrar hallazgos y decisiones (sin LLM)
rb report "El módulo de auth necesita refactoring"
rb log-decision "Usar PostgreSQL" "El equipo tiene experiencia profunda"

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

Flask, ripgrep, Vite y Prometheus · 20 preguntas × 3 repeticiones por producto · mismo acceso al código y ruta de modelo (Seed-2.1-Turbo → seed-code-pro).

Los fallos cuentan como respuestas incorrectas. La construcción en frío compara generación completa de conocimiento con IA e indexación estática del grafo de código, no cargas equivalentes. Los resultados solo se aplican a este experimento con versiones fijadas.

Resultados completos y metodología

¡Las ideas también son contribuciones! Abre un issue para reportar bugs, sugerir funcionalidades o proponer arquitectura.

⭐ Lling0000 Contribuidor Principal · Sugerencias creativas · Administrador del proyecto · Ideación y feedback	Alexander Daza Sandbox MVP · Workflows OpenSpec · Docs de análisis técnico · PHILOSOPHY	Chen Yi Primer prototipo CLI · Refactor de 753 líneas · Extracción DummyClient · Docs quick-start	Subham Sangwan Carga dinámica de herramientas (#4) · Protocolo swarm multi-agente (#3)	shuofengzhang Fix ventana de contexto de memoria · Manejo graceful de cierre MCP (#28)
goodmorning10 Mejora de carga de contexto en rb ask — añadió CONTEXT.md, AGENTS.md y memory/*.md como fuentes de contexto (#29)	BBear0115 Empaquetado de skills y mejoras de recuperación KG · Sincronización README multilingüe (#30)	SunkenCost Comando rb clean · Protección de entrada __main__ (#37)	Aravindh Balaji Superficie de instrucciones unificada en torno a AGENTS.md (#41)
xiaolai Feedback de auditoría NLPM · Fixes de frontmatter de skills · Revisión de higiene de dependencias (#51, #52, #53)

Licencia MIT. Ver LICENSE para detalles.