CodeSeeker

CodeSeeker

Busca híbrida em quatro camadas e grafo de conhecimento para assistentes de codificação com IA.
BM25 + embeddings vetoriais + resumos de diretórios RAPTOR + expansão de grafo — fundidos em uma única ferramenta MCP que dá ao Claude, Copilot e Cursor um entendimento real do seu código.

Funciona com Claude Code, GitHub Copilot (VS Code 1.99+), Cursor, Windsurf e Claude Desktop.
Um comando para indexar; o plugin do Claude Code mantém tudo sincronizado a partir daí.

Construído pela PragmaWorks como parte da Generative Specification — a disciplina para construir software com IA que não se desvia. Dois servidores MCP irmãos compõem com este, cada um resolvendo uma metade diferente do mesmo problema:

Eles são independentes: instale um, ou todos os três.

Quando você não vai mais precisar disso

O CodeSeeker resolve um problema de recuperação, e esse problema está diminuindo.

Se você executa um loop orientado por especificação com um harness real — uma especificação precisa o suficiente para que um modelo sem estado derive dela, e portões de qualidade que verificam o resultado contra um sistema ao vivo — ou um orientado por intenção, seu assistente está recebendo a estrutura que de outra forma teria que procurar. Uma ferramenta sentinela que roteia ações em vez de se espalhar por uma dúzia de endpoints remove outra fatia da busca. Modelos de fronteira com melhor navegação e maior contexto efetivo removem mais. Além de certo ponto, a busca semântica sobre seu próprio código deixa de ser o gargalo, e este servidor se torna algo que você poderia desinstalar sem notar.

Esse é o resultado pretendido, não um defeito: um método que funciona deve tornar seu próprio andaime desnecessário. A maioria das equipes não começa aí, no entanto, e até que o processo esteja em vigor, o CodeSeeker é o substituto mais barato — um comando em vez de uma disciplina.

Se você prefere ter o processo em vez do substituto, comece pelo guia de campo: Generative Specification — Field Guide (PDF).

O Problema

Assistentes de IA são editores poderosos, mas navegam pelo código como um turista:

• Grep encontra texto — não significado. "find authentication logic" retorna todos os arquivos que contêm a palavra "auth"
• Leituras de arquivo são isoladas — o Claude vê um arquivo, mas não suas dependências, chamadores ou os padrões que sua equipe estabeleceu
• Sem memória do seu projeto — toda sessão começa do zero

O CodeSeeker resolve isso. Ele indexa seu código uma vez e dá aos assistentes de IA um grafo de conhecimento consultável que eles podem usar a cada turno.

Como Funciona

Um pipeline de 4 estágios roda em cada consulta:

Query: "find JWT refresh token logic"
        │
        ▼  Stage 1 — Hybrid retrieval
   ┌─────────────────────────────────────────────────────┐
   │ BM25 (exact symbols, camelCase tokenized)           │
   │   +                                                 │
   │ Vector search (384-dim Xenova embeddings)           │
   │   ↓                                                 │
   │ Reciprocal Rank Fusion: score = Σ 1/(60 + rank_i)  │
   │ Top-30 results, including RAPTOR directory nodes    │
   └─────────────────────────────────────────────────────┘
        │
        ▼  Stage 2 — RAPTOR cascade (conditional)
   ┌─────────────────────────────────────────────────────┐
   │ IF best directory-summary score ≥ 0.5:              │
   │   → narrow results to that directory automatically  │
   │ ELSE: all 30 results pass through unchanged         │
   │ Effect: "what does auth/ do?" scopes to auth/       │
   │         "jwt.ts decode function" bypasses this      │
   └─────────────────────────────────────────────────────┘
        │
        ▼  Stage 3 — Scoring and deduplication
   ┌─────────────────────────────────────────────────────┐
   │ Dedup: keep highest-score chunk per file            │
   │ Source files:  +0.10  (definition sites matter)     │
   │ Test files:    −0.15  (prevent test dominance)      │
   │ Symbol boost:  +0.20  (query token in filename)     │
   │ Multi-chunk:   up to +0.30  (file has many hits)    │
   └─────────────────────────────────────────────────────┘
        │
        ▼  Stage 4 — Graph expansion
   ┌─────────────────────────────────────────────────────┐
   │ Top-10 results → follow IMPORTS/CALLS/EXTENDS edges │
   │ Structural neighbors scored at source × 0.7        │
   │ Avg graph connectivity: 20.8 edges/node             │
   └─────────────────────────────────────────────────────┘
        │
        ▼
   auth/jwt.ts (0.94), auth/refresh.ts (0.89), ...

O grafo de conhecimento é construído a partir de imports analisados por AST no momento da indexação. É o que alimenta a ação graph, detecção de código morto e expansão de grafo em cada busca.

O Que o Torna Diferente

O que ferramentas LSP não conseguem fazer:

• "Encontre código que lida com erros assim" → busca semântica de padrões
• "Qual abordagem de validação este projeto usa?" → padrões de codificação detectados automaticamente
• "Mostre-me tudo relacionado a autenticação" → travessia de grafo através de dependências indiretas

O que a busca somente vetorial perde:

• Cadeias diretas de import/export
• Hierarquias de herança de classes
• Quais arquivos realmente dependem de quais

Instalação

Recomendado: instale uma vez, configure uma vez

npm install -g codeseeker
claude mcp add codeseeker --scope user -e CODESEEKER_STORAGE_MODE=embedded -- codeseeker serve --mcp

--scope user o torna disponível em todos os projetos que você abre, não apenas no atual.

Por que global em vez de npx -y: em uma máquina que nunca viu o pacote, o npx o baixa e compila dependências nativas antes que o servidor possa responder, o que mediu 13,7 segundos até um handshake MCP concluído. Clientes que desistem mais cedo relatam isso como uma falha de conexão. Uma instalação global responde em 759 ms — o download acontece uma vez, em um momento em que você está esperando por isso.

npx (sem instalação)

Portátil, e tudo bem uma vez que o pacote esteja em cache. Espere um primeiro início lento.

{
  "mcpServers": {
    "codeseeker": {
      "command": "npx",
      "args": ["-y", "codeseeker", "serve", "--mcp"],
      "env": { "CODESEEKER_STORAGE_MODE": "embedded" }
    }
  }
}

Adicione isso ao seu arquivo de configuração MCP (veja abaixo para locais por cliente) e reinicie seu editor.

Outros editores

npm install -g codeseeker
codeseeker install --vscode      # or --cursor, --windsurf, --vs

🔌 Plugin Claude Code

Para usuários do Claude Code CLI — adiciona hooks de sincronização automática e comandos de barra:

/plugin install codeseeker@github:jghiringhelli/codeseeker#plugin

Comandos de barra: /codeseeker:init, /codeseeker:reindex

☁️ Devcontainers / GitHub Codespaces

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:18",
  "postCreateCommand": "npm install -g codeseeker && codeseeker install --vscode"
}

✅ Verificação

Pergunte ao seu assistente de IA: "Quais ferramentas do CodeSeeker você tem?"

Você deve ver uma única ferramenta chamada codeseeker. Isso é intencional: uma ferramenta com uma chave de roteamento action mantém a sobrecarga de tokens por requisição baixa (ADR-002). As ações são search, sym, graph, analyze e index.

Opções Avançadas de Instalação

{
  "mcpServers": {
    "codeseeker": {
      "command": "npx",
      "args": ["-y", "codeseeker", "serve", "--mcp"]
    }
  }
}

npm install -g codeseeker
cd your-project
codeseeker init
codeseeker -c "how does authentication work in this project?"

O Que Você Obtém

O CodeSeeker expõe uma ferramenta MCP, codeseeker. Você escolhe o comportamento com action e preenche apenas o grupo de parâmetros aninhados correspondente:

codeseeker({ action, project, search?|sym?|graph?|analyze?|index? })

Sempre passe project (a raiz absoluta do projeto) — um servidor MCP não consegue detectar seu diretório de trabalho.

Você não invoca isso manualmente — o Claude usa automaticamente ao buscar código ou analisar relacionamentos.

Como Funciona a Indexação

Você não precisa indexar nada primeiro. Buscar um projeto que o CodeSeeker nunca viu inicia o índice automaticamente e avisa. A indexação roda em segundo plano, então a chamada retorna imediatamente em vez de bloquear seu assistente:

User: "Find the authentication logic"
        │
        ▼
┌────────────────────────────────────────────────────────┐
│ Claude calls codeseeker({action:"search"})             │
│         │                                              │
│         ▼                                              │
│ Project indexed? ──No──► starts indexing, returns      │
│         │                {status:"indexing_started"}   │
│        Yes                                             │
│         ▼                                              │
│ Return ranked results + confidence                     │
└────────────────────────────────────────────────────────┘

Então a primeira pergunta que você faz a um novo projeto responde com "indexação iniciada, tente novamente em breve" em vez de resultados. Um projeto pequeno fica pronto em alguns segundos; um grande leva vários minutos. Verifique com index({op:"status"}) em vez de adivinhar.

Você ainda pode indexar deliberadamente, e vale a pena para um repositório grande para que a espera aconteça quando você espera:

codeseeker({ action: "index", index: { op: "init", path: "/abs/path", name: "my-project" } })

codeseeker init          # or, from the CLI

name é a única coisa que um init explícito dá que o automático não pode saber — caso contrário, o projeto é registrado sob o nome do seu diretório.

Mantendo o índice atualizado

O índice é um instantâneo. Nada monitora seu sistema de arquivos, então depois que os arquivos mudam, há três maneiras de ele voltar a ficar em sincronia:

Sem o plugin, um índice que se desatualiza continuará retornando resultados; eles simplesmente serão do código como era. O sinal stale_index é o que revela isso.

Pesquisa de Qualidade de Busca

npm run build
node scripts/real-bench.js

Padrões de Codificação Auto-Detectados

O CodeSeeker analisa seu codebase e extrai padrões:

{
  "validation": {
    "email": {
      "preferred": "z.string().email()",
      "usage_count": 12,
      "files": ["src/auth.ts", "src/user.ts"]
    }
  },
  "react-patterns": {
    "state": {
      "preferred": "useState<T>()",
      "usage_count": 45
    }
  }
}

Categorias de padrões detectados:

• validação: Zod, Yup, Joi, validator.js, regex personalizado
• tratamento de erros: respostas de erro de API, padrões try-catch, classes de Error personalizadas
• logging: Console, Winston, Bunyan, logging estruturado
• testes: configuração Jest/Vitest, padrões de asserção
• padrões-react: Hooks (useState, useEffect, useMemo, useCallback, useRef)
• gerenciamento de estado: Redux Toolkit, Zustand, React Context, TanStack Query
• padrões-de-api: Fetch, Axios, rotas Express, rotas Next.js API

Quando o Claude escreve código novo, ele segue suas convenções existentes em vez de inventar novas.

Gerenciando Exclusões de Índice

Se o Claude notar arquivos que não deveriam ser indexados (como a pasta Library do Unity, saídas de build ou arquivos gerados), ele pode excluí-los dinamicamente:

// Exclude Unity Library folder and generated files
codeseeker({
  action: "index",
  project: "/abs/path/to/my-unity-game",
  index: {
    op: "exclude",
    exclude_op: "exclude",
    paths: ["Library/**", "Temp/**", "*.generated.cs"],
    reason: "Unity build artifacts"
  }
})

As exclusões são persistidas em .codeseeker/exclusions.json e respeitadas automaticamente durante a reindexação.

Ferramentas de Limpeza de Código

O CodeSeeker ajuda você a manter um codebase limpo, encontrando código duplicado e detectando código morto.

Encontrando Código Duplicado

Peça ao Claude para encontrar blocos de código semelhantes que poderiam ser consolidados:

"Find duplicate code in my project"
"Are there any similar functions that could be merged?"
"Show me copy-pasted code that should be refactored"

O CodeSeeker usa similaridade vetorial para encontrar código semanticamente semelhante — não apenas correspondências exatas. Ele detecta:

• Funções copiadas e coladas com pequenas variações
• Lógica de validação semelhante entre arquivos
• Padrões repetidos que poderiam ser extraídos em utilitários

Encontrando Código Morto

Peça ao Claude para identificar código não utilizado que pode ser removido com segurança:

"Find dead code in this project"
"What functions are never called?"
"Show me unused exports"

O CodeSeeker analisa o grafo de conhecimento para encontrar:

• Funções/classes exportadas que nunca são importadas
• Funções internas sem chamadores
• Arquivos órfãos sem dependências de entrada

Exemplo de fluxo de trabalho:

User: "Use CodeSeeker to clean up this project"

Claude: I'll analyze your codebase for cleanup opportunities.

Found 3 duplicate code blocks:
- validateEmail() in auth.ts and user.ts (92% similar)
- formatDate() appears in 4 files with minor variations
- Error handling pattern repeated in api/*.ts

Found 2 dead code files:
- src/utils/legacy-helper.ts (0 imports)
- src/services/unused-service.ts (exported but never imported)

Would you like me to:
1. Consolidate the duplicate validators into a shared utility?
2. Remove the dead code files?

Suporte a Linguagens

Toda linguagem é indexada e pesquisável — a divisão em chunks e os embeddings não dependem de um parser. O que o parser altera é o grafo de conhecimento: com que precisão o CodeSeeker sabe qual símbolo é uma declaração e do que depende.

A extração por regex é uma limitação real, não uma versão menor da mesma coisa. Ela encontra declarações pela forma, então perde qualquer coisa escrita de forma incomum e não consegue distinguir uma declaração de uma chamada. As arestas de importação permanecem confiáveis para TypeScript e JavaScript, onde o Babel as analisa; as arestas de chamada são heurísticas em todos os lugares.

As classificações acima são medidas, não afirmadas. scripts/corpus-bench.js indexa sete projetos reais e scripts/graph-quality.js relata quanto de cada grafo resultante é plausivelmente uma declaração real. Java não tem classificação própria porque nenhum projeto Java está nesse corpus; ele compartilha o caminho de código Tree-sitter do Python, e isso é tudo o que podemos afirmar.

Medido nas quatro implementações RealWorld Conduit — o mesmo aplicativo escrito quatro vezes, então uma lacuna entre elas é tratamento de linguagem e não dificuldade da tarefa — o rank recíproco médio em 30 consultas rotuladas é TypeScript 83,3%, Python 81,5%, JavaScript 77,1%, C# 70,5%.

Adicionando um parser para sua linguagem

Se seu projeto é majoritariamente Go, Rust, C++ ou Ruby, você pode instalar a gramática Tree-sitter para ele:

npm install -g tree-sitter-go        # or tree-sitter-rust, tree-sitter-cpp, …

Então pergunte ao seu assistente, ou execute:

codeseeker({ action: "index", project: "/abs/path", index: { op: "parsers", list_available: true } })

A resposta marca cada parser com wired: true ou wired: false. Apenas um parser marcado como wired: true é consumido pelo construtor de grafos — instalar um marcado como false não muda nada hoje, e a resposta diz isso em vez de deixar você descobrir por não notar uma melhoria.

Atualmente conectados: TypeScript, JavaScript, Python, Java, C#. Os outros são false honestos. Conectar um é uma mudança pequena e autocontida — um parser implementando ILanguageParser registrado em extensionToParser (src/mcp/indexing-service.ts) — e contribuições são bem-vindas. scripts/graph-quality.js mede se um novo parser realmente melhorou o grafo, então a melhoria é demonstrável em vez de assumida.

Mantendo o Índice Sincronizado

Com o Plugin do Claude Code

O plugin instala hooks que atualizam automaticamente o índice:

Você não precisa fazer nada — o plugin lida com a sincronização automaticamente.

Apenas com o Servidor MCP (Cursor, Claude Desktop)

• Mudanças iniciadas pelo Claude: Claude pode chamar codeseeker({action:"index", index:{op:"sync"}})
• Mudanças manuais: Não detectadas automaticamente — peça ao Claude para reindexar periodicamente

Resumo de Sincronização

Quando o CodeSeeker Ajuda Mais

Bom ajuste:

• Codebases grandes (10K+ arquivos) onde o Claude tem dificuldade em encontrar código relevante
• Projetos com padrões estabelecidos que você quer que o Claude siga
• Cadeias de dependência complexas entre vários arquivos
• Equipes que querem código gerado por IA consistente

Menos útil:

• Projetos greenfield com pouco código existente
• Scripts de arquivo único
• Projetos onde você está mudando ativamente a arquitetura

Arquitetura

┌──────────────────────────────────────────────────────────┐
│                     Claude Code                          │
│                         │                                │
│                    MCP Protocol                          │
│                         │                                │
│  ┌──────────────────────▼──────────────────────────┐    │
│  │              CodeSeeker MCP Server               │    │
│  │  ┌─────────────┬─────────────┬────────────────┐ │    │
│  │  │   Vector    │  Knowledge  │    Coding      │ │    │
│  │  │   Search    │    Graph    │   Standards    │ │    │
│  │  │  (SQLite)   │  (SQLite)   │   (JSON)       │ │    │
│  │  └─────────────┴─────────────┴────────────────┘ │    │
│  └─────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────┘

Todos os dados armazenados localmente em .codeseeker/. Nenhum serviço externo necessário.

Para equipes grandes (100K+ arquivos, índices compartilhados), o modo servidor suporta PostgreSQL + Neo4j. Veja Documentação de Armazenamento.

Para os detalhes técnicos completos — fórmulas exatas de pontuação, esquema de ferramentas MCP, tipos de arestas do grafo, lógica de limite do RAPTOR, estágios do pipeline, níveis de confiança da análise — veja o Manual Técnico de Arquitetura.

Solução de Problemas

Servidor MCP não conectando

1. Verifique se npm e npx funcionam: npx -y codeseeker --version
2. Verifique a sintaxe do arquivo de configuração MCP (JSON válido, sem vírgulas finais)
3. Reinicie completamente seu editor/aplicativo Claude
4. Verifique se o Node.js está instalado: node --version (precisa de v18+)

Indexação parece lenta

A indexação inicial de projetos grandes (50K+ arquivos) pode levar 5+ minutos. Usos subsequentes são instantâneos.

Ferramentas não aparecendo no Claude

1. Pergunte ao Claude: "Quais ferramentas do CodeSeeker você tem?"
2. Se nenhuma ferramenta aparecer, verifique se o arquivo de configuração MCP existe e tem a sintaxe correta
3. Reinicie completamente seu IDE (não apenas recarregue a janela)
4. Verifique o status da conexão MCP do Claude/Copilot no IDE

Ainda travado?

Abra uma issue: GitHub Issues

Documentação

• Guia de Integração - Como todos os componentes se conectam
• Arquitetura - Mergulho técnico profundo
• Comandos CLI - Referência completa de comandos

Plataformas Suportadas

Claude Code e GitHub Copilot compartilham o mesmo .vscode/mcp.json — configure uma vez, funciona para ambos.

Suporte

Se o CodeSeeker é útil para você, considere patrocinar o projeto.

Licença

Apache License 2.0. Veja LICENSE e NOTICE.

Gratuito para qualquer uso, incluindo comercial — sem limites de tamanho de empresa ou receita. Apache-2.0 adiciona uma concessão explícita de patente sobre o MIT, e é por isso que é a escolha aqui.

Executando o CodeSeeker em uma equipe

Tudo acima é a configuração local, de desenvolvedor único: o índice vive em .codeseeker/ na sua máquina e nunca sai dela.

Existe uma implantação centralizada para equipes — um índice compartilhado sobre os repositórios da sua organização (PostgreSQL + pgvector, Neo4j), para que engenheiros não paguem cada um para reindexar o mesmo código, e para que o grafo atravesse fronteiras de serviço em vez de parar em um único repositório. Também revela o que a ferramenta local estruturalmente não consegue: como o entendimento de código está realmente distribuído em um codebase e onde estão as lacunas de conhecimento.

Se isso for útil para sua equipe, entre em contato: https://pragmaworks.dev

O CodeSeeker dá ao Claude o entendimento de código que grep e embeddings sozinhos não conseguem fornecer.

Parte da Especificação Generativa

Uma ferramenta Apache-2.0 por trás da Especificação Generativa (GS) — a disciplina para construir software com IA que não se desvia: você cria uma especificação precisa o suficiente para que uma IA sem estado derive código correto dela, e um harness a verifica contra um sistema vivo.

• 📄 White paper (acesso aberto): https://doi.org/10.5281/zenodo.21726017
• 📕 Guia de campo — o caminho curto e prático para começar: https://github.com/jghiringhelli/generative-specification/blob/main/docs/white-paper/GenerativeSpecification_FieldGuide.pdf
• 🧭 Comece aqui — método, ferramentas, depoimentos: https://pragmaworks.dev
• 🔨 A Forja — workshop prático de GS de 2 dias para sua equipe: https://forgeworkshop.dev