rag-rat

rag-rat

O que um repositório sabe sobre si mesmo. rag-rat é um índice local de inteligência de repositório e um servidor MCP para agentes de codificação. Ele mantém os arquivos-fonte somente leitura, grava apenas em seu próprio banco de dados SQLite e responde com proveniência em cada resultado — código-fonte atual, o grafo de código, histórico git/GitHub e memórias de repositório duráveis e ancoradas no código-fonte que persistem entre sessões e agentes.

Explore a demonstração ao vivo do VS Code Lens — sem necessidade de instalação. Ela exibe classes duplicadas, memórias de repositório e contexto de issues/decisões junto ao código; pressione Ctrl+Alt+R para revelar sobreposições de clones.

Todo ambiente de codificação já tem grep e leitura de arquivos. O rag-rat adiciona a camada que eles não fornecem: racional ancorado no código-fonte. Ele conecta o código que um agente está prestes a tocar aos seus chamadores, chamados, testes, histórico git/GitHub, decisões anteriores, invariantes, riscos e sinais de código duplicado — e rotula cada resultado com confiança e cobertura, para que um agente possa julgá-lo em vez de confiar cegamente.

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ê

• Proveniência, não suposições. Cada resultado carrega um rótulo de confiança, avisos de cobertura e a evidência bruta — para que um índice parcial ou uma aresta ambígua seja lida exatamente como tal.
• Memórias de repositório. Notas tipadas e ancoradas no código-fonte (Invariant, Decision, Risk, …) que sobrevivem a refatorações e aparecem automaticamente em consultas futuras — o sinal que o grep não consegue dar. Elas não são memória de assistente: são fatos versionados, locais e ancorados no código-fonte sobre este repositório que qualquer agente futuro recupera com evidência.
• Um grafo de código real. Chamadores/chamados/imports via tree-sitter em Rust, TypeScript/TSX, Kotlin, C/C++, Python, Swift e Go — com um oráculo SCIP de nível compilador opcional para toolchains configurados que eleva as arestas para confiança Compiler e classifica os símbolos estruturais.
• Histórico como evidência. Histórico Git, blame preguiçoso de chunks e racional de issues/PRs/reviews do GitHub em cache, tudo consultável.
• Destilação de issues. Cada issue fechada e PR mesclado mais seu diff de correção destilado em um registro de decisão tipado — causa raiz, a abordagem que foi adotada (e as alternativas rejeitadas) e o resultado — validado contra a thread e exibido como contexto incidental nos símbolos ancorados.
• Acompanha seu grep existente. Um hook de aumento de grep injeta as memórias e símbolos por trás do que você acabou de pesquisar.
• Sinaliza clones enquanto você os escreve. Um hook PreToolUse em Write/Edit/MultiEdit coleta as impressões digitais das funções que você está escrevendo e avisa quando elas são duplicatas exatas ou quase duplicatas de código já presente no repositório — para que um agente reutilize em vez de reimplementar. Somente leitura e um no-op silencioso quando o índice não está pronto, para nunca bloquear uma escrita.

Início rápido

Para Claude Code, Codex e opencode, instale o plugin. Ele registra o servidor MCP, adiciona os hooks e baixa um binário rag-rat compatível com a versão na primeira execução, que o servidor MCP expõe como ~/.local/bin/rag-rat quando inicia — veja Executando a CLI (os pacotes do Claude Code e Codex também adicionam as skills; no opencode, adicione-as com 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

Após instalar, aprove o plugin para que suas ferramentas e hooks sejam executados (o opencode carrega plugins sem etapa de aprovação — nada a fazer lá):

• Claude Code pergunta antes de cada ferramenta MCP do rag-rat na primeira execução — escolha "Sim, não perguntar novamente" ou pré-permita-as em ~/.claude/settings.json com "permissions": { "allow": ["mcp__plugin_rag-rat_rag-rat__*"] } (as ferramentas do plugin são nomeadas mcp__plugin_rag-rat_rag-rat__<tool>; um servidor adicionado manualmente com claude mcp add usa mcp__rag-rat__* em vez disso).

• Codex mostra um prompt "Hooks precisam de revisão" na primeira sessão codex iniciada dentro do repositório (o plugin inclui hooks de aumento de grep, verificação de clones e resumo de sessão que são executados fora do sandbox). Escolha "Confiar em tudo e continuar" para habilitá-los. Para comandos não assistidos, como codex review, também permita as ferramentas MCP do plugin em ~/.codex/config.toml para que a execução não trave em um prompt de aprovação por ferramenta:

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

  Isso confia em todas as ferramentas MCP atuais e futuras expostas pelo plugin rag-rat instalado. Ative-o somente quando confiar na origem do plugin e na origem da instalação e, em seguida, reinicie o Codex.

Depois, abra o repositório e pergunte:

Configure o rag-rat neste repositório.

A skill init-rag-rat escaneia o repositório, explica as escolhas materiais, pré-visualiza rag-rat.toml, grava e indexa somente após confirmação e oferece configurar os hooks do git que mantêm o índice atualizado. O servidor MCP inicia dormente em um repositório não configurado; quando a configuração terminar, reconecte-o para que reinicie totalmente ativo contra o novo índice — no Claude Code, execute /mcp e reconecte rag-rat; no Codex e no opencode, inicie uma nova sessão.

Depois, coloque-o para trabalhar — o ciclo para o qual o rag-rat foi construído está em Experimente.

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__*"] } }

Experimente

Assim que o repositório for indexado, o grafo de código, símbolos, histórico git, busca semântica e detecção de clones estarão prontos — eles respondem na primeira consulta. As memórias de repositório começam vazias: elas se acumulam à medida que os agentes registram descobertas com memory_create e depois aparecem automaticamente em respostas posteriores. (O racional de issues/PRs do tracker precisa de um rag-rat papertrail sync.)

Pergunte ao seu cliente MCP:

• "Execute impact_surface na função que estou prestes a editar — seus chamadores, chamados, testes e commits recentes."
• "Onde o recarregamento de configuração é tratado?" — semantic_search híbrido sobre código-fonte e documentação.
• "Quais são os símbolos mais estruturais deste repositório?" — important_symbols.
• "Este helper duplica algo que já existe no código?" — find_clones (e o hook em tempo de escrita avisa enquanto você escreve).
• "Registre um invariante em parse_config: o recarregamento não deve alocar após o início do agendador." — memory_create grava sua primeira memória de repositório; ela então acompanha resultados futuros de impact_surface / symbol_lookup.

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

O ciclo do agente

O ponto não é o catálogo de ferramentas — é o ciclo que um agente executa em torno de uma edição, para que ele altere o código com os chamadores, testes, racional e trabalhos anteriores à sua frente, em vez de adivinhar:

1. Antes de editar um símbolo, pergunte a impact_surface. Uma única chamada retorna a âncora de código-fonte atual, chamadores e chamados, testes relacionados, racional git/GitHub, as memórias de repositório vinculadas a esse símbolo / caminho / caminho de chamada e avisos de confiança + cobertura.
2. Leia o raio de impacto e depois edite. O invariante que um agente anterior registrou, o chamador a três saltos de distância, o teste que fixa o comportamento — tudo exibido antes da mudança, não descoberto depois.
3. O hook de clones detecta duplicação em tempo de escrita. Se a nova função reimplementa código que já existe, o hook Write/Edit informa isso, com o símbolo existente para reutilizar.
4. Registre o que você aprendeu. Quando a edição revela um invariante durável, uma decisão ou uma armadilha, memory_create armazena isso como uma memória de repositório ancorada no código-fonte — para que o próximo agente (ou a próxima sessão) receba isso em uma única chamada, em vez de redescobrir.

Uma resposta impact_surface resumida (TOON — a saída padrão; abreviada aqui) — cada campo é evidência, não 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."

E o aviso de clone em tempo de escrita que um agente vê antes de duplicar lógica — saída do hook, verbatim:

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

As ferramentas

O catálogo de ferramentas do rag-rat é exposto tanto via MCP quanto por comandos nativos da CLI. O catálogo completo e os esquemas JSON estão documentados em docs/mcp-tools.md. Execute rag-rat tools --help para navegar por todas as ferramentas ou rag-rat tools <name> --help para inspecionar argumentos a partir do esquema canônico. Comandos curados existentes, como query, brief, memory e dream, permanecem inalterados. Os que você mais usará:

• impact_surface — o preflight de codificação do loop acima: chamadores, chamados, testes, histórico do git, trilha de auditoria do GitHub e as memórias do repositório que cruzam um símbolo, em uma única chamada. As memórias padrão são cabeçalhos compactos e escaneáveis; passe full_memories: true para corpos completos + vínculos.
• semantic_search — recall híbrido BM25 + vetorial sobre código-fonte e documentação, validado contra o código-fonte atual. Cada resultado reporta retrieval_mode; explain=true detalha a pontuação.
• symbol_lookup — resolução de símbolo exata/aproximada; variantes de cfg/overload agrupadas como um único símbolo lógico.
• find_callers / trace_callees — travessia do grafo de chamadas reverso/direto (ruído de baixo sinal de std/macro filtrado por padrão).
• important_symbols — os símbolos de maior carga por PageRank (ciente de SCIP), semeados a partir do seu diff atual por padrão; veja docs/oracle.md.
• find_clones — funções duplicadas exatas e quase idênticas classificadas por ROI de refatoração (o grafo candidato é pré-computado em segundo plano, então escala para repositórios grandes).
• memory_create — registra uma memória de repositório ancorada no código-fonte; dream traz à tona a lista de tarefas de manutenção que as mantém honestas (abaixo).

Além disso: orientação no repositório (repo_brief, repo_clusters), histórico e justificativas (history_for um símbolo, caminho, trecho ou commit; history_search sobre commits, issues e discussão de revisão), recall de memória (memory_search, memory_for_*) e saúde do índice (index_status). Manutenção e diagnósticos — dream, heal_index, memory_doctor, auditorias de grafo vs. compilador, o grafo de tarefas de memória — estão nos conjuntos de ferramentas opcionais admin e graph ([mcp] toolsets), então ficam fora da lista de ferramentas de cada agente até serem desejados. Tudo documentado em docs/mcp-tools.md.

Memórias de repositório

Memórias de repositório são evidências locais de primeira classe — não são memória de chat, nem personalização em nuvem. São fatos versionados, locais e ancorados no código-fonte sobre este repositório. Cada uma é tipada (Invariant, Decision, RejectedAlternative, Risk, BugPattern, PerformanceNote, …) e ancorada no código-fonte: vinculada a um símbolo lógico, símbolo concreto, trecho, caminho+intervalo, aresta do grafo, caminho de chamada, commit ou referência do GitHub. rag-rat rastreia cada âncora como current, relocated, stale, gone ou unverified, e traz à tona memórias correspondentes através das ferramentas memory_* e inline em read_chunk, symbol_lookup, find_callers, trace_callees e impact_surface. É assim que o contexto conquistado com esforço chega ao próximo agente em uma única chamada, em vez de evaporar.

Memórias também são um grafo tipado, não apenas uma lista plana: memory_edge_add / memory_edges as conectam com relações (depends_on, relates_to, supersedes, derived_from, tracks) — um DAG de tarefas, um link de mapa mental entre decisões, ou uma tarefa que tracks uma issue do GitHub. Lista completa de ferramentas: docs/mcp-tools.md.

Memórias autogerenciáveis

Memórias apodrecem: o código se move sob elas, uma invariante é substituída, uma função de alta carga é lançada sem nenhuma memória. dream é o loop de manutenção que mantém a camada honesta. Ele recalcula uma lista de tarefas classificada de descobertas sobre as próprias memórias — cada uma com um id estável para revisão:

• lacunas de cobertura — símbolos de alta carga (pelo mesmo PageRank de important_symbols) que não carregam memória, então o próximo agente que os editar não recebe nada.
• referências obsoletas — uma memória citando um caminho ou âncora que não resolve mais.

dream executa as descobertas determinísticas em cada chamada. Duas passagens de modelo opcionais vão mais fundo, executando um modelo pequeno em uma GPU remota efêmera ([llm.dream.remote]) somente quando há trabalho pendente: rag-rat dream --verify recalcula o veredito de cada memória contra a realidade atual do código-fonte (o código se desviou do que a memória afirma?), e --compact reescreve uma memória verbosa em um resumo mais enxuto. As descobertas que essas passagens persistem voltam à tona através de dream.

Nada é excluído automaticamente. Um humano — ou um agente forte via MCP — reduz a lista de tarefas com dream_review (accept uma lacuna real, dismiss ruído, reset um veredito anterior), e os vereditos sobrevivem a execuções futuras para que descobertas resolvidas não voltem. É a mesma superfície que o CLI rag-rat dream / rag-rat dream <id> --accept|--dismiss|--reset.

Resolução e classificação de nível de compilador

O grafo é heurístico por padrão. O oráculo SCIP opcional (rag-rat oracle run) atualiza as arestas para um nível Compiler a partir de uma ferramenta de linguagem real, recupera chamadas que o tree-sitter perdeu, sinaliza arestas externas e faz important_symbols trazer à tona os verdadeiros módulos centrais. Para C/C++, o oráculo scip-clang distingue declarações de definições e aprimora as arestas de chamada/tipo em código com muitos macros ou múltiplos alvos — a diferença entre grafos utilizáveis e ruidosos em firmware, kernels, drivers e SDKs. Ative [oracle] auto_run e o servidor MCP o mantém atualizado por conta própria (limitado, seguro para watchers). Detalhes completos: docs/oracle.md.

Atualização

rag-rat mcp executa um watcher de arquivos em segundo plano (ativado por padrão; [watch] enabled = false ou RAG_RAT_NO_WATCH=1 para desativar), então consultas de grafo/símbolo refletem edições não commitadas sem um commit. As linhas indexadas são cientes do contexto git: arquivos limpos são armazenados por commit_sha, arquivos sujos/não rastreados em uma sobreposição de worktree, então um único banco de dados reutiliza linhas entre trocas de branch enquanto reflete edições locais. Hooks git opcionais (rag-rat hooks install) mantêm o índice atualizado em checkout/merge/rewrite/commit. read_chunk e a busca validam resultados contra o código-fonte atual e curam entradas obsoletas antes de retornar.

Um watcher por worktree e um escritor por vez são garantidos com bloqueios de arquivo (não confiáveis em montagens NFS / WSL2 /mnt).

API HTTP Editor Lens

Um processo rag-rat mcp ativo também elege um servidor HTTP Lens autenticado por worktree. Ele publica a URL de loopback e o token bearer em .rag-rat/sockets/lens.json; o arquivo de credenciais é legível apenas pelo proprietário no Unix. Defina RAG_RAT_NO_LENS=1 para desativar este servidor embutido, ou defina RAG_RAT_LENS_ORIGINS para uma lista de permissões de origens de navegador exatas separadas por vírgula.

Execute rag-rat serve quando a API HTTP precisar de seu próprio ciclo de vida. O serviço de loopback gera um token; os clientes o leem do arquivo de descoberta. Um bind não-loopback exige tanto uma variável de ambiente de token explícita quanto pelo menos uma origem de navegador confiável:

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 requisição não-preflight usa Authorization: Bearer <token>. As origens permitidas são correspondidas exatamente; CORS curinga nunca é emitido. O listener embutido é HTTP simples, então termine o TLS em um proxy reverso ou túnel confiável antes de expor um servidor não-loopback em uma rede não confiável.

Por padrão, o índice e as memórias de cada repositório vivem em um banco de dados consolidado por máquina ($XDG_DATA_HOME/rag-rat/rag-rat.sqlite; substitua com RAG_RAT_DATA_DIR), então um checkout excluído ou git clean -fdx não perde mais suas memórias autorais. Defina um [index] database explícito para manter um repositório em seu próprio arquivo (obsoleto) e execute rag-rat consolidate para importar um .rag-rat/index.sqlite pré-existente no armazenamento global — veja docs/config/database.md.

Formato de saída

Os resultados do CLI e do MCP usam por padrão TOON (Token-Oriented Object Notation) — uma codificação eficiente em tokens que renderiza linhas uniformes como uma tabela [N]{cols}: densa (~30% menor que JSON compacto nesses payloads, nunca maior na prática). Passe --json (CLI, em qualquer posição) ou inicie rag-rat mcp --json (MCP) quando um parser JSON precisar ler a saída.

Backends de embeddings

O embedder local padrão (FastEmbed) não precisa de configuração, mas um repositório grande ou um modelo mais forte vale a pena ser descarregado. rag-rat fala a API /v1/embeddings compatível com OpenAI, então um bloco [llm.embedding.remote] pode servir embeddings de Ollama, vLLM ou michaelfeil/infinity — um cliente, um lugar para auditar e proteger. Dois modos:

• Conectar a um servidor que você já executa (defina endpoint).
• Efêmero — deixe o cookbook incluído provisionar um worker de GPU (Modal / RunPod) apenas para o backfill e derrubá-lo depois (defina cookbook); escolha o backend e a classe de GPU na configuração.

O fluxo de inicialização avisa quando um modelo de contexto curto truncaria trechos de código longos e o direciona para um embedder de código de contexto longo, e rag-rat ajusta automaticamente a concorrência do cliente contra o backend escolhido para que a varredura encontre seu ponto de rendimento. Configuração e cada botão: docs/config.md.

Qualidade de recuperação

A qualidade da busca é mensurável, não um palpite. rag-rat inclui um harness de avaliação por replay de commits (rag-rat eval --replay): cada commit recente vira um caso — sua mensagem é a consulta, os arquivos que ele tocou são o conjunto dourado — e a busca é pontuada em quão bem ela os recupera. Ele reporta recall@3 (o trecho certo caiu nas três primeiras leituras?), recall@10 e MRR@10, e o CI rastreia a tendência no Bencher em main para que uma regressão seja pega antes de ser lançada.

Use-o ao comparar modelos de embedding, mudar o chunking, habilitar armazenamento vetorial int8 (menor em disco) ou ajustar um backend remoto — você pode provar que a mudança não custou recall em vez de esperar. (rag-rat eval requer um build --features eval; está ausente do binário lançado.)

Benchmarks

A carga de trabalho principal é indexar todo o kernel Linux (v7.0, ~63k arquivos C/H, 9,14M arestas de grafo). Números completos — wall-clock, throughput, pico de RSS, tamanho em disco, taxonomia de arestas não resolvidas — estão em docs/benchmarks.md. O desempenho é rastreado por push e limitado por PR; o histórico ao vivo está em bencher.dev/perf/rag-rat/plots (cabeamento: docs/bencher.md).

Segurança

O servidor MCP expõe ferramentas de código-fonte somente leitura. Ele nunca executa comandos de shell nem escreve seus arquivos de código-fonte. Ele escreve apenas o índice SQLite configurado — durante indexação, migração, manutenção, reconciliação, operações de memória de repositório e cura automática de índice obsoleto. A sincronização do GitHub é explícita e usa gh api; as ferramentas de consulta normais leem apenas o cache local.

Embedding local vs. remoto

Com o embedder local padrão, nada sai da máquina — indexação e consulta são inteiramente locais. Configurar um backend [llm.embedding.remote] é o que envia texto para fora da máquina, em dois lugares: o texto do trecho selecionado no momento da indexação e o texto da consulta de cada busca semântica (uma busca incorpora sua consulta para compará-la com os vetores indexados). Um backend CONNECT incorpora ambos contra o endpoint configurado; um backend efêmero incorpora consultas contra o query_endpoint local.

O que o endpoint é decide o quanto isso importa:

• Seu próprio servidor (Ollama / vLLM / infinity auto-hospedados) — o texto permanece na infraestrutura que você controla.
• Workers efêmeros Modal / RunPod (o caminho do cookbook) são provedores de computação efêmera executando seu embedder de código aberto, não serviços de dados que treinam com entradas. Ambos são SOC 2 Tipo II, criptografam em trânsito e em repouso, isolam locatários e derrubam a máquina e seu armazenamento após o backfill — uma relação de processador de dados, razoável para código proprietário da mesma forma que uma VM em nuvem.
• Uma API de embedding de terceiros que você não controla é a única em que você deve realmente ler os termos (retenção, treinamento com entradas).

Higiene sensata independentemente do backend: exclua segredos, arquivos gerados e árvores de fornecedores dos alvos indexados para que nunca sejam divididos em trechos ou incorporados, e mantenha segredos fora do texto da consulta. Detalhes: docs/config.md.

Suporte de plataforma

rag-rat compila e testa em Linux, macOS e Windows. Linux é coberto em todos os PRs e em todos os pushes para a main; macOS e Windows são exercitados em releases, então cargo install rag-rat compila e linka nos três. Android (aarch64, bionic) também é um alvo de release — um binário pré-compilado é anexado a cada release e publicado em @rag-rat/bin, então npx @rag-rat/bin funciona no Termux; veja Quickstart. SQLite é embutido (compilado a partir do código-fonte via rusqlite), então não há pré-requisito de biblioteca do sistema, mas cada plataforma precisa de um toolchain C: Linux já vem com um; no macOS instale as Xcode Command Line Tools (xcode-select --install); no Windows instale o Visual Studio Build Tools com a carga de trabalho C++ (MSVC). Requer Rust 1.98+; o workspace acompanha essa baseline estável para suas dependências (a compilação do SQLite embutido exige pelo menos Rust 1.95 para cfg_select!).

Algumas conveniências de manutenção são exclusivas de Unix ou Linux por design e degradam silenciosamente em outros lugares — nenhum recurso do índice, consulta ou superfície MCP é afetado:

• Hot-upgrade de um servidor MCP em execução (o SIGUSR1 re-exec in-place) é exclusivo de Unix. No Windows, reinicie rag-rat mcp para usar um novo binário.
• Auto-upgrade de frota (sinalizar outros servidores em execução quando um novo binário chega) é exclusivo de Linux — ele percorre /proc — e é um no-op em outros lugares.
• O hook de aumento de grep usa um listener de Unix-socket aquecido (com dedupe por sessão) em Linux e macOS; no Windows ele cai para uma consulta somente leitura por chamada direta contra o índice, que funciona da mesma forma, mas sem dedupe entre chamadas.

Comandos

Executando a CLI

Comandos neste README e em docs/ são escritos como rag-rat <command>.

Com o plugin, rag-rat é ~/.local/bin/rag-rat (Windows: %USERPROFILE%\.local\bin\rag-rat.cmd): o servidor MCP mantém esse shim apontando para o binário com versão correspondente do plugin desde sua primeira inicialização, e o move adiante quando o plugin atualiza. Como o instalador do Claude Code, ele não edita seu perfil de shell ou PATH. Se rag-rat não for encontrado, ~/.local/bin não está no seu PATH — adicione export PATH="$HOME/.local/bin:$PATH" ao seu perfil de shell, ou execute ~/.local/bin/rag-rat doctor, cuja seção cli dá a correção exata para o seu sistema. O shim nunca substitui um rag-rat lá que ele não criou; RAG_RAT_NO_PATH_SHIM=1 desativa isso.

Sem o plugin, instale a CLI: npm install -g @rag-rat/bin ou cargo install rag-rat.

Último recurso, sem nenhum dos dois, execute via npx fixado na versão que seu servidor MCP usa (o campo version da ferramenta index_status):

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

Mantenha a versão: um npx @rag-rat/bin sem fixação executa o release mais recente, que migra o índice para um esquema que o servidor de um plugin mais antigo depois se recusa a abrir. Git hooks se fixam dessa forma e seguem atualizações do plugin por conta própria.

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

Releases e licença

Releases são automatizados por release-plz (os três crates são lançados em conjunto; veja docs/releasing.md). rag-rat é licenciado sob MIT — veja LICENSE.

Trabalhos relacionados

O design de detecção de clones do rag-rat é inspirado na geração de candidatos por token-bag escalável do SourcererCC, no enquadramento de detecção de clones near-miss normalizados do NiCad, no diffing de AST ciente de movimentação do GumTree, e na anti-unificação / generalização menos geral para extração de templates. A mineração planejada em nível de fragmento e as heurísticas de bugs de copiar-e-colar são inspiradas no CP-Miner.