rag-rat

rag-rat

Lo que un repositorio sabe sobre sí mismo. rag-rat es un índice local de inteligencia de repositorio y un servidor MCP para agentes de codificación. Mantiene los archivos fuente de solo lectura, escribe únicamente en su propia base de datos SQLite y responde con procedencia en cada resultado: fuente actual, grafo de código, historial de git/GitHub y memorias de repositorio ancladas a la fuente que persisten entre sesiones y agentes.

Explora la demo en vivo de VS Code Lens — no requiere instalación. Muestra clases duplicadas, memorias de repositorio y contexto de incidencias/decisiones junto al código; presiona Ctrl+Alt+R para revelar superposiciones de clones.

Cada entorno de codificación ya tiene grep y lecturas de archivos. rag-rat añade la capa que no proporcionan: razón de ser anclada a la fuente. Conecta el código que un agente está a punto de tocar con sus llamadores, llamados, pruebas, historial de git/GitHub, decisiones previas, invariantes, riesgos y señales de código duplicado — y etiqueta cada resultado con confianza y cobertura, para que un agente pueda juzgarlo en lugar de confiar ciegamente.

sequenceDiagram
    participant Repo as Repository
    participant Engine as rag-rat engine
    participant Agent as Coding agent

    Repo->>Engine: Source · git/GitHub · repo memories
    Engine->>Engine: Index → graph → (opt) SCIP oracle → reconcile
    Agent->>Engine: where / why / who-calls / impact?
    Engine-->>Agent: source + call paths + papertrail + memories (with provenance)
    Agent->>Engine: record a finding
    Engine->>Repo: persist a source-anchored repo memory

Por qué

• Procedencia, no suposiciones. Cada resultado lleva una etiqueta de confianza, advertencias de cobertura y la evidencia cruda — para que un índice parcial o un caso límite ambiguo se lea exactamente como tal.
• Memorias de repositorio. Notas tipadas y ancladas a la fuente (Invariant, Decision, Risk, …) que sobreviven a refactorizaciones y aparecen automáticamente durante consultas futuras — la señal que grep no puede darte. No son memoria del asistente: son hechos versionados, locales y anclados a la fuente sobre este repositorio que cualquier agente futuro recupera con evidencia.
• Un grafo de código real. Llamadores/llamados/importaciones de tree-sitter en Rust, TypeScript/TSX, Kotlin, C/C++, Python, Swift y Go — con un oráculo SCIP de grado compilador opcional para cadenas de herramientas configuradas que mejora las aristas a confianza Compiler y clasifica los símbolos de mayor carga.
• Historial como evidencia. Historial de git, blame diferido de chunks y razón de ser de incidencias/PRs/revisiones de GitHub en caché, todo consultable.
• Destilación de incidencias. Cada incidencia cerrada y PR fusionado más su diff correctivo destilado en un registro de decisión tipado — causa raíz, el enfoque que se adoptó (y las alternativas rechazadas) y el resultado — validado contra el hilo y mostrado como contexto incidental en los símbolos anclados.
• Aprovecha tu grep existente. Un gancho de aumento de grep inyecta las memorias y símbolos detrás de lo que acabas de buscar.
• Marca clones mientras los escribes. Un gancho PreToolUse en Write/Edit/MultiEdit toma la huella de las funciones que estás escribiendo y advierte cuando son duplicados exactos o casi duplicados de código ya existente en el repositorio — para que un agente reutilice en lugar de reimplementar. Solo lectura, y un no-op silencioso cuando el índice no está listo, por lo que nunca bloquea una escritura.

Inicio rápido

Para Claude Code, Codex y opencode, instala el plugin. Registra el servidor MCP, añade los ganchos y descarga un binario rag-rat con versión coincidente en la primera ejecución, que el servidor MCP expone como ~/.local/bin/rag-rat cuando se inicia — consulta Ejecutar la CLI (los paquetes de Claude Code y Codex también añaden las habilidades; en opencode añádelas con npx @rag-rat/skills):

# Claude Code
claude plugin marketplace add cq27-dev/rag-rat
claude plugin install rag-rat@rag-rat

# Codex
codex plugin marketplace add cq27-dev/rag-rat
codex plugin add rag-rat@rag-rat

# opencode (add -g for a global install)
opencode plugin @rag-rat/plugin-opencode

Después de instalar, aprueba el plugin para que sus herramientas y ganchos se ejecuten (opencode carga plugins sin un paso de aprobación — no hay nada que hacer allí):

• Claude Code pregunta antes de cada herramienta MCP de rag-rat la primera vez que se ejecuta — elige "Sí, no preguntar de nuevo", o pre-autorízalas en ~/.claude/settings.json con "permissions": { "allow": ["mcp__plugin_rag-rat_rag-rat__*"] } (las herramientas del plugin se nombran mcp__plugin_rag-rat_rag-rat__<tool>; un servidor añadido manualmente con claude mcp add usa mcp__rag-rat__* en su lugar).

• Codex muestra un aviso de "Hooks need review" en la primera sesión de codex iniciada dentro del repositorio (el plugin incluye ganchos de aumento de grep, verificación de clones y resumen de sesión que se ejecutan fuera del sandbox). Elige "Trust all and continue" para habilitarlos. Para comandos desatendidos como codex review, también permite las herramientas MCP del plugin en ~/.codex/config.toml para que la ejecución no se detenga en un aviso de aprobación por herramienta:

  [plugins."rag-rat@rag-rat".mcp_servers.rag-rat]
  default_tools_approval_mode = "approve"
  

  Esto confía en todas las herramientas MCP actuales y futuras expuestas por el plugin rag-rat instalado. Solo habilítalo cuando confíes en la fuente del plugin y el origen de instalación, luego reinicia Codex.

Luego abre el repositorio y pregunta:

Configura rag-rat en este repositorio.

La habilidad init-rag-rat escanea el repositorio, explica las opciones materiales, previsualiza rag-rat.toml, escribe e indexa solo después de la confirmación, y ofrece configurar los ganchos de git que mantienen el índice actualizado. El servidor MCP se inicia inactivo en un repositorio no configurado; cuando la configuración termine, reconéctalo para que se reinicie completamente activo contra el nuevo índice — en Claude Code ejecuta /mcp y reconecta rag-rat; en Codex y opencode, inicia una nueva sesión.

Luego ponlo a trabajar — el bucle para el que rag-rat está construido está en Pruébalo.

npm install -g @rag-rat/bin
# or run it without installing:
npx @rag-rat/bin --help

cargo install rag-rat
# or from a checkout:
cargo install --path crates/rag-rat-cli --bin rag-rat

cargo install rag-rat --no-default-features --features model2vec

cd /path/to/your/repo
rag-rat init

npx @rag-rat/skills

claude mcp add --scope project rag-rat -- rag-rat mcp
codex  mcp add rag-rat -- rag-rat mcp

{
  "mcpServers": {
    "rag-rat": { "command": "rag-rat", "args": ["mcp"] }
  }
}

{ "permissions": { "allow": ["mcp__rag-rat__*"] } }

Pruébalo

Una vez que el repositorio está indexado, el grafo de código, los símbolos, el historial de git, la búsqueda semántica y la detección de clones están listos — estos responden en la primera consulta. Las memorias de repositorio comienzan vacías: se acumulan a medida que los agentes registran hallazgos con memory_create y luego aparecen automáticamente en respuestas posteriores. (La razón de ser de incidencias/PRs del rastreador necesita un rag-rat papertrail sync.)

Pregunta a tu cliente MCP:

• "Ejecuta impact_surface en la función que estoy a punto de editar — sus llamadores, llamados, pruebas y confirmaciones recientes."
• "¿Dónde se maneja la recarga de configuración?" — semantic_search híbrido sobre código fuente y documentación.
• "¿Cuáles son los símbolos de mayor carga en este repositorio?" — important_symbols.
• "¿Este helper duplica algo que ya existe en el código base?" — find_clones (y el gancho en tiempo de escritura advierte mientras lo escribes).
• "Registra un invariante en parse_config: la recarga no debe asignar memoria después de que el programador se inicie." — memory_create escribe tu primera memoria de repositorio; luego viaja en futuros resultados de impact_surface / symbol_lookup.

O desde la CLI:

rag-rat query "where is config reload handled?"
rag-rat important-symbols --limit 20
rag-rat brief --mode spine
rag-rat clusters --limit 10
rag-rat tools impact-surface --symbol parse_config

El bucle del agente

El punto no es el catálogo de herramientas — es el bucle que un agente ejecuta alrededor de una edición, para que cambie el código con los llamadores, pruebas, razón de ser y trabajo previo frente a él en lugar de adivinar:

1. Antes de editar un símbolo, pregunta a impact_surface. Una sola llamada devuelve el ancla de fuente actual, llamadores y llamados, pruebas relacionadas, razón de ser de git/GitHub, las memorias de repositorio vinculadas a ese símbolo / ruta / ruta de llamada, y advertencias de confianza + cobertura.
2. Lee el radio de impacto, luego edita. El invariante que un agente anterior registró, el llamador a tres saltos de distancia, la prueba que fija el comportamiento — todo aparece antes del cambio, no se descubre después.
3. El gancho de clones detecta duplicación en tiempo de escritura. Si la nueva función reimplementa código que ya existe, el gancho de Write/Edit lo dice, con el símbolo existente para reutilizar.
4. Registra lo que aprendiste. Cuando la edición revela un invariante duradero, una decisión o una trampa, memory_create lo almacena como una memoria de repositorio anclada a la fuente — para que el próximo agente (o la próxima sesión) lo obtenga en una sola llamada en lugar de volver a derivarlo.

Una respuesta impact_surface recortada (TOON — la salida predeterminada; abreviada aquí) — cada campo es evidencia, no prosa:

query:
  ref: "crates/config/src/config.rs::parse_config"
  resolution: syntactic
direct_semantic_callers[12]:
  - from_symbol: "crates/runtime/src/boot.rs::start"
    edge_kind: calls_name
    confidence: syntactic
    callsite:
      path: "crates/runtime/src/boot.rs"
      line: 88
    importance:
      label: local structural load
      score: 6.8
      bucket: high
tests_touching_symbol_path[4]:
  - path: "crates/config/src/config_tests.rs"
    reason: test_mentions_symbol_or_path
recent_commits_touching_symbol_path[1]:
  - evidence[1]: "a1b2c3d touched crates/config/src/config.rs: fix reload race during startup (#141)"
repo_memories:
  direct[2]:
    - kind: Invariant
      title: "Config reload must not allocate after the scheduler starts"
      confidence: high
      anchor_status: current
      binding_kind: symbol
    - kind: Decision
      title: "TOML over JSON5 for the config surface (#88)"
      anchor_status: current
      binding_kind: path
completeness_and_caveats:
  exact_graph_callers: 12
  memory_status:
    active: 2
    stale: 0
  caveats[1]: "Graph evidence is tree-sitter/syntactic, not compiler-grade name resolution."

Y la advertencia de clon en tiempo de escritura que un agente ve antes de duplicar lógica — salida del gancho textual:

▶ rag-rat clone check — code you're writing duplicates existing functions:
  • `normalize_path_for_lookup` (line 42) is ~91% similar to crates/index/src/paths.rs::canonicalize_lookup_path
Prefer reusing the existing function(s) over duplicating — impact_surface / symbol_lookup to inspect them.

Las herramientas

El catálogo de herramientas de rag-rat se expone tanto a través de MCP como de comandos CLI nativos. El catálogo completo y los esquemas JSON están documentados en docs/mcp-tools.md. Ejecuta rag-rat tools --help para explorar cada herramienta o rag-rat tools <name> --help para inspeccionar argumentos desde el esquema canónico. Los comandos curados existentes como query, brief, memory y dream permanecen sin cambios. Los que usarás con más frecuencia:

• impact_surface — la verificación previa de codificación del bucle anterior: llamadores, llamados, pruebas, historial de git, rastro de GitHub y las memorias del repositorio que cruzan un símbolo, en una sola llamada. Las memorias por defecto son encabezados compactos y escaneables; pasa full_memories: true para cuerpos completos + enlaces.
• semantic_search — recuperación híbrida BM25 + vectorial sobre código fuente y documentación, validada contra el código fuente actual. Cada acierto reporta retrieval_mode; explain=true desglosa la puntuación.
• symbol_lookup — resolución de símbolos exacta/difusa; las variantes de cfg/sobrecarga se agrupan como un símbolo lógico.
• find_callers / trace_callees — recorrido del grafo de llamadas inverso/directo (el ruido de bajo nivel de std/macro se filtra por defecto).
• important_symbols — los símbolos de mayor carga por PageRank (consciente de SCIP), sembrados desde tu diff actual por defecto; consulta docs/oracle.md.
• find_clones — funciones duplicadas exactas y casi coincidentes clasificadas por ROI de refactorización (el grafo candidato se precalcula en segundo plano, por lo que escala a repositorios grandes).
• memory_create — registra una memoria de repositorio anclada al código fuente; dream saca a la superficie la lista de trabajo de mantenimiento que las mantiene honestas (abajo).

Más allá de esto: orientación del repositorio (repo_brief, repo_clusters), historial y justificación (history_for un símbolo, ruta, fragmento o commit; history_search sobre commits, issues y discusión de revisión), recuperación de memoria (memory_search, memory_for_*) y salud del índice (index_status). Mantenimiento y diagnósticos — dream, heal_index, memory_doctor, auditorías grafo-vs-compilador, el grafo de tareas de memoria — están en los conjuntos de herramientas opcionales admin y graph ([mcp] toolsets), por lo que permanecen fuera de la lista de herramientas de cada agente hasta que se deseen. Todo documentado en docs/mcp-tools.md.

Memorias del repositorio

Las memorias del repositorio son evidencia local de primera clase — no memoria de chat, no personalización en la nube. Son hechos versionados, locales y anclados al código fuente sobre este repositorio. Cada una está tipada (Invariant, Decision, RejectedAlternative, Risk, BugPattern, PerformanceNote, …) y anclada al código fuente: vinculada a un símbolo lógico, símbolo concreto, fragmento, ruta+extensión, borde del grafo, ruta de llamada, commit o referencia de GitHub. rag-rat rastrea cada ancla como current, relocated, stale, gone o unverified, y saca a la superficie memorias coincidentes a través de las herramientas memory_* y en línea en read_chunk, symbol_lookup, find_callers, trace_callees y impact_surface. Así es como el contexto ganado con esfuerzo llega al siguiente agente en una sola llamada en lugar de evaporarse.

Las memorias también son un grafo tipado, no solo una lista plana: memory_edge_add / memory_edges las conectan con relaciones (depends_on, relates_to, supersedes, derived_from, tracks) — un DAG de tareas, un enlace de mapa mental entre decisiones, o una tarea que tracks un issue de GitHub. Lista completa de herramientas: docs/mcp-tools.md.

Memorias autosostenibles

Las memorias se deterioran: el código se mueve debajo de ellas, una invariante queda superada, una función de carga se publica sin ninguna memoria en absoluto. dream es el bucle de mantenimiento que mantiene la capa honesta. Recalcula una lista de trabajo clasificada de hallazgos sobre las propias memorias — cada una con un id estable para revisar:

• brechas de cobertura — símbolos de carga (por el mismo PageRank que important_symbols) que no llevan memoria, por lo que el siguiente agente que los edite no obtiene nada.
• referencias obsoletas — una memoria que cita una ruta o ancla que ya no se resuelve.

dream ejecuta los hallazgos deterministas en cada llamada. Dos pasadas de modelo opcionales van más profundo, ejecutando un modelo pequeño en una GPU remota efímera ([llm.dream.remote]) solo cuando hay trabajo pendiente: rag-rat dream --verify recalcula el veredicto de cada memoria contra la realidad actual del código fuente (¿ha derivado el código de lo que la memoria afirma?), y --compact reescribe una memoria verbosa a un resumen más ajustado. Los hallazgos que esas pasadas persisten se vuelven a mostrar a través de dream.

Nada se elimina automáticamente. Un humano — o un agente fuerte sobre MCP — reduce la lista de trabajo con dream_review (accept una brecha real, dismiss ruido, reset un veredicto anterior), y los veredictos sobreviven a ejecuciones futuras para que los hallazgos resueltos no vuelvan. Es la misma superficie que el CLI rag-rat dream / rag-rat dream <id> --accept|--dismiss|--reset.

Resolución y clasificación de grado compilador

El grafo es heurístico por defecto. El oráculo SCIP opcional (rag-rat oracle run) actualiza los bordes a un nivel Compiler desde una herramienta de lenguaje real, recupera llamadas que tree-sitter omitió, marca bordes externos y hace que important_symbols saque a la superficie los verdaderos módulos centrales. Para C/C++, el oráculo scip-clang distingue declaraciones de definiciones y afina los bordes de llamada/tipo en código con muchas macros o múltiples objetivos — la diferencia entre grafos utilizables y ruidosos en firmware, kernels, controladores y SDKs. Activa [oracle] auto_run y el servidor MCP lo mantiene fresco por sí solo (limitado, seguro para watchers). Detalles completos: docs/oracle.md.

Frescura

rag-rat mcp ejecuta un watcher de archivos en segundo plano (activado por defecto; [watch] enabled = false o RAG_RAT_NO_WATCH=1 para desactivarlo), por lo que las consultas de grafo/símbolo reflejan ediciones no confirmadas sin un commit. Las filas indexadas son conscientes del contexto de git: los archivos limpios se almacenan por commit_sha, los archivos sucios/no rastreados en una superposición de árbol de trabajo, por lo que una base de datos reutiliza filas entre cambios de rama mientras refleja ediciones locales. Los hooks de git opcionales (rag-rat hooks install) mantienen el índice actualizado en checkout/merge/rewrite/commit. read_chunk y la búsqueda validan los aciertos contra el código fuente actual y curan entradas obsoletas antes de devolverlas.

Se aplica un watcher por árbol de trabajo y un escritor a la vez con bloqueos de archivo (no confiables en montajes NFS / WSL2 /mnt).

API HTTP de Editor Lens

Un proceso rag-rat mcp activo también elige un servidor Lens HTTP autenticado por árbol de trabajo. Publica la URL de loopback y el token de portador en .rag-rat/sockets/lens.json; el archivo de credenciales es legible solo por el propietario en Unix. Establece RAG_RAT_NO_LENS=1 para desactivar este servidor integrado, o establece RAG_RAT_LENS_ORIGINS a una lista de permitidos de orígenes de navegador exactos separados por comas.

Ejecuta rag-rat serve cuando la API HTTP necesite su propio ciclo de vida. El servicio de loopback genera un token; los clientes lo leen del archivo de descubrimiento. Un enlace no-loopback requiere tanto una variable de entorno de token explícita como al menos un origen de navegador confiable:

LENS_TOKEN="$(openssl rand -hex 32)" rag-rat serve \
  --bind 0.0.0.0 --token-env LENS_TOKEN --allow-origin https://lens.example.com

Cada solicitud que no es de verificación previa usa Authorization: Bearer <token>. Los orígenes permitidos se comparan exactamente; el CORS comodín nunca se emite. El listener integrado es HTTP simple, por lo que termina TLS en un proxy inverso o túnel confiable antes de exponer un servidor no-loopback a través de una red no confiable.

Por defecto, el índice y las memorias de cada repositorio viven en una base de datos consolidada por máquina ($XDG_DATA_HOME/rag-rat/rag-rat.sqlite; anula con RAG_RAT_DATA_DIR), por lo que un checkout eliminado o git clean -fdx ya no pierde tus memorias autoriales. Establece un [index] database explícito para mantener un repositorio en su propio archivo (obsoleto), y ejecuta rag-rat consolidate para importar un .rag-rat/index.sqlite preexistente al almacén global — consulta docs/config/database.md.

Formato de salida

Los resultados del CLI y MCP por defecto usan TOON (Token-Oriented Object Notation) — una codificación eficiente en tokens que renderiza filas uniformes como una tabla densa [N]{cols}: (~30% más pequeña que JSON compacto en esos payloads, nunca más grande en la práctica). Pasa --json (CLI, en cualquier posición) o lanza rag-rat mcp --json (MCP) cuando un parser JSON deba leer la salida.

Backends de incrustación

El embedder local por defecto (FastEmbed) no necesita configuración, pero un repositorio grande o un modelo más fuerte vale la pena descargarlo. rag-rat habla la API /v1/embeddings compatible con OpenAI, por lo que un bloque [llm.embedding.remote] puede servir incrustaciones desde Ollama, vLLM o michaelfeil/infinity — un cliente, un lugar para auditar y asegurar. Dos modos:

• Conectar a un servidor que ya ejecutas (establece endpoint).
• Efímero — deja que el cookbook incluido aprovisione un trabajador GPU (Modal / RunPod) solo para el backfill y lo derribe después (establece cookbook); elige el backend y la clase de GPU en la configuración.

El flujo de inicialización advierte cuando un modelo de contexto corto truncaría fragmentos de código largos y te dirige a un embedder de código de contexto largo, y rag-rat ajusta automáticamente la concurrencia del cliente contra el backend elegido para que el barrido encuentre su punto de rendimiento. Configuración y cada perilla: docs/config.md.

Calidad de recuperación

La calidad de búsqueda es medible, no una suposición. rag-rat incluye un harness de evaluación de reproducción de commits (rag-rat eval --replay): cada commit reciente se convierte en un caso — su mensaje es la consulta, los archivos que tocó son el conjunto dorado — y la búsqueda se puntúa por qué tan bien los recupera. Reporta recall@3 (¿cayó el fragmento correcto en las primeras tres lecturas?), recall@10 y MRR@10, y CI rastrea la tendencia en Bencher en main para que una regresión se detecte antes de que se publique.

Úsalo al comparar modelos de incrustación, cambiar el fragmentado, habilitar almacenamiento de vectores int8 (más pequeño en disco) o ajustar un backend remoto — puedes probar que el cambio no costó recall en lugar de esperar. (rag-rat eval requiere una compilación --features eval; está ausente del binario publicado.)

Benchmarks

La carga de trabajo principal es indexar todo el kernel de Linux (v7.0, ~63k archivos C/H, 9.14M bordes de grafo). Números completos — tiempo de pared, rendimiento, RSS máximo, tamaño en disco, taxonomía de bordes no resueltos — están en docs/benchmarks.md. El rendimiento se rastrea por push y se controla por PR; el historial en vivo está en bencher.dev/perf/rag-rat/plots (cableado: docs/bencher.md).

Seguridad

El servidor MCP expone herramientas de código fuente de solo lectura. Nunca ejecuta comandos de shell ni escribe tus archivos de código fuente. Solo escribe el índice SQLite configurado — durante indexación, migración, mantenimiento, reconciliación, operaciones de memoria de repositorio y curación automática de índices obsoletos. La sincronización de GitHub es explícita y usa gh api; las herramientas de consulta normales solo leen la caché local.

Incrustación local vs remota

Con el embedder local por defecto, nada sale de la máquina — la indexación y las consultas son completamente locales. Configurar un backend [llm.embedding.remote] es lo que envía texto fuera de la caja, en dos lugares: el texto del fragmento seleccionado en el momento de la indexación, y el texto de la consulta de cada búsqueda semántica (una búsqueda incrusta tu consulta para compararla contra los vectores indexados). Un backend CONNECT incrusta ambos contra el endpoint configurado; un backend efímero incrusta consultas contra el query_endpoint local.

Lo que es el endpoint decide cuánto importa eso:

• Tu propio servidor (Ollama / vLLM / infinity autoalojados) — el texto permanece en infraestructura que controlas.
• Trabajadores efímeros Modal / RunPod (la ruta del cookbook) son proveedores de cómputo efímeros que ejecutan tu embedder de código abierto, no servicios de datos que entrenan con entradas. Ambos son SOC 2 Tipo II, cifran en tránsito y en reposo, aíslan inquilinos y derriban la caja y su almacenamiento después del backfill — una relación de procesador de datos, razonable para código propietario de la misma manera que una VM en la nube.
• Una API de incrustación de terceros que no controlas es la única donde realmente debes leer los términos (retención, entrenamiento con entradas).

Higiene sensata independientemente del backend: excluye secretos, archivos generados y árboles de proveedores de los objetivos indexados para que nunca se fragmenten o incrusten, y mantén los secretos fuera del texto de consulta. Detalles: docs/config.md.

Soporte de plataforma

rag-rat se compila y prueba en Linux, macOS y Windows. Linux está cubierto en cada PR y en cada push a main; macOS y Windows se ejercitan en los lanzamientos, por lo que cargo install rag-rat se compila y enlaza en los tres. Android (aarch64, bionic) también es un objetivo de lanzamiento: un binario precompilado se adjunta a cada lanzamiento y se publica en @rag-rat/bin, por lo que npx @rag-rat/bin funciona en Termux; consulta Quickstart. SQLite está incluido (compilado desde el código fuente mediante rusqlite), por lo que no hay requisito de biblioteca del sistema, pero cada plataforma necesita un conjunto de herramientas C: Linux incluye uno; en macOS instala las Xcode Command Line Tools (xcode-select --install); en Windows instala las Visual Studio Build Tools con la carga de trabajo C++ (MSVC). Requiere Rust 1.98+; el workspace sigue esa línea base estable para sus dependencias (la compilación de SQLite incluida requiere al menos Rust 1.95 para cfg_select!).

Algunas conveniencias de mantenimiento son solo Unix o Linux por diseño y se degradan silenciosamente en otros lugares: ninguna característica del índice, la consulta o la superficie MCP se ve afectada:

• Actualización en caliente de un servidor MCP en ejecución (el re-ejecución en el lugar de SIGUSR1) es solo Unix. En Windows, reinicia rag-rat mcp para recoger un nuevo binario.
• Actualización automática de flota (señalando a otros servidores en ejecución cuando llega un nuevo binario) es solo Linux: recorre /proc — y es una no-operación en otros lugares.
• El hook de aumento de grep usa un listener de socket Unix cálido (con deduplicación por sesión) en Linux y macOS; en Windows recurre a una consulta de solo lectura por llamada directamente contra el índice, que funciona igual pero sin deduplicación entre llamadas.

Comandos

Ejecutar la CLI

Los comandos en este README y en docs/ están escritos como rag-rat <command>.

Con el plugin, rag-rat es ~/.local/bin/rag-rat (Windows: %USERPROFILE%\.local\bin\rag-rat.cmd): el servidor MCP mantiene ese shim apuntando al binario con versión coincidente del plugin desde su primer inicio, y lo avanza cuando el plugin se actualiza. Como el instalador de Claude Code, no edita tu perfil de shell ni tu PATH. Si rag-rat no se encuentra, ~/.local/bin no está en tu PATH: agrega export PATH="$HOME/.local/bin:$PATH" a tu perfil de shell, o ejecuta ~/.local/bin/rag-rat doctor, cuya sección cli da la solución exacta para tu sistema. El shim nunca reemplaza un rag-rat allí que no haya creado; RAG_RAT_NO_PATH_SHIM=1 lo desactiva.

Sin el plugin, instala la CLI: npm install -g @rag-rat/bin o cargo install rag-rat.

Último recurso, sin ninguno de los dos, ejecútalo a través de npx fijado a la versión que ejecuta tu servidor MCP (el campo version de la herramienta index_status):

npx -y @rag-rat/bin@<version> <command>

Mantén la versión: un npx @rag-rat/bin sin fijar ejecuta el lanzamiento más reciente, que migra el índice a un esquema que el servidor de un plugin más antiguo luego se niega a abrir. Los hooks de Git se fijan a sí mismos de esta manera y siguen las actualizaciones del plugin por su cuenta.

rag-rat init                       # guided first-run setup
rag-rat index [--changed|--discover|--full]
rag-rat doctor
rag-rat query "semantic recall"    # add --json for JSON
rag-rat important-symbols --limit 20
rag-rat brief --mode spine|churn|god_modules|refactor_candidates
rag-rat clusters --limit 10
rag-rat oracle run | status        # compiler-grade resolution (docs/oracle.md)
rag-rat models list | install <model>
rag-rat reconcile --changed-first --max-seconds 60 --batch-size 64
rag-rat papertrail sync            # add --full to force a historical healing pass
rag-rat memory list | show <id> | doctor | rebind <id>    # inspect / re-anchor repo memories
rag-rat dream [--verify|--compact] [<id> --accept|--dismiss|--reset]   # memory-maintenance worklist
rag-rat consolidate                # import a legacy per-repo index into the global store
rag-rat hooks install              # git maintenance hooks
rag-rat gc                         # prune rows for dead git contexts
rag-rat eval [--json|--update-baseline]   # CI search-quality gate; requires a `--features eval` build (absent from the released binary)
rag-rat serve                      # authenticated editor Lens HTTP API
rag-rat tools <name>               # invoke any tool directly; see `tools --help`
rag-rat mcp                        # start the STDIO server

Lanzamiento y licencia

Los lanzamientos están automatizados por release-plz (las tres crates se publican en conjunto; consulta docs/releasing.md). rag-rat tiene licencia MIT: consulta LICENSE.

Trabajo previo

El diseño de detección de clones de rag-rat está inspirado en la generación escalable de candidatos por bolsa de tokens de SourcererCC, el marco de detección de clones de casi-omisiones normalizados de NiCad, el diffing de AST consciente de movimientos de GumTree, y la anti-unificación / generalización menos general para la extracción de plantillas. La minería planificada a nivel de fragmentos y las heurísticas de errores de copiar y pegar están inspiradas en CP-Miner.