CodeSeeker

CodeSeeker

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

Funciona com Claude Code, GitHub Copilot (VS Code 1.99+), Cursor, Windsurf e Claude Desktop.
Zero configuração — indexa no primeiro uso, mantém-se sincronizado automaticamente.

O Problema

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

• 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 — 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 — cada sessão começa do zero

CodeSeeker resolve isso. Ele indexa seu codebase uma vez e dá aos assistentes de IA um grafo de conhecimento consultável que eles podem usar a cada interação.

Como Funciona

Um pipeline de 4 estágios é executado 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. É ele que alimenta analyze dependencies, 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 de padrões semânticos
• "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 por 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: npx (sem necessidade de instalação)

A forma padrão de configurar qualquer servidor MCP — sem instalação global necessária:

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

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

Instalação global via npm

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

🔌 Plugin Claude Code

Para usuários da CLI do Claude Code — 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: search, analyze, index — as três ferramentas do CodeSeeker.

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

Uma vez configurado, Claude tem acesso a estas ferramentas MCP (usadas automaticamente):

Você não invoca estas ferramentas manualmente — Claude as usa automaticamente ao buscar código ou analisar relações.

Como Funciona a Indexação

Você não precisa indexar manualmente. Quando Claude usa qualquer ferramenta do CodeSeeker, a ferramenta verifica automaticamente se o projeto está indexado. Se não estiver, ela indexa no primeiro uso.

User: "Find the authentication logic"
        │
        ▼
┌─────────────────────────────────────┐
│ Claude calls search({query: ...})  │
│         │                           │
│         ▼                           │
│ Project indexed? ──No──► Index now  │
│         │                  (auto)   │
│        Yes                   │      │
│         │◀───────────────────┘      │
│         ▼                           │
│ Return search results               │
└─────────────────────────────────────┘

A primeira busca em um novo projeto leva de 30 segundos a vários minutos (dependendo do tamanho). Buscas subsequentes são instantâneas.

Pesquisa sobre Qualidade de Busca

npm run build
node scripts/real-bench.js

Padrões de Codificação Detectados Automaticamente

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:

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

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

Gerenciando Exclusões de Índice

Se 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
index({
  action: "exclude",
  project: "my-unity-game",
  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

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

Encontrando Código Duplicado

Peça a 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"

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 a 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"

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

Fluxo de trabalho de exemplo:

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

Os parsers Tree-sitter são instalados automaticamente quando necessário.

Mantendo o Índice Sincronizado

Com o Plugin do Claude Code

O plugin instala hooks que atualizam o índice automaticamente:

Você não precisa fazer nada — o plugin cuida da sincronização automaticamente.

Somente com o Servidor MCP (Cursor, Claude Desktop)

• Alterações iniciadas pelo Claude: Claude pode chamar a ferramenta index({action: "sync"})
• Alterações manuais: Não são detectadas automaticamente — peça ao Claude para reindexar periodicamente

Resumo da Sincronização

Quando o CodeSeeker Mais Ajuda

Bom para:

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

Menos útil:

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

Arquitetura

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

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

Para equipes grandes (100K+ arquivos, índices compartilhados), o modo servidor suporta PostgreSQL + Neo4j. Consulte Storage Documentation.

Para os detalhes técnicos completos — fórmulas exatas de pontuação, esquema das 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 — consulte o Technical Architecture Manual.

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 o seu editor/aplicativo Claude
4. Verifique se o Node.js está instalado: node --version (necessário v18+)

Indexação parece lenta

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

Ferramentas não aparecem 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 o seu IDE (não apenas recarregue a janela)
4. Verifique o status da conexão MCP do Claude/Copilot no IDE

Ainda com problemas?

Abra um issue: GitHub Issues

Documentação

• Integration Guide - Como todos os componentes se conectam
• Architecture - Mergulho técnico aprofundado
• CLI Commands - 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 for útil para você, considere patrocinar o projeto.

Licença

Licença MIT. Consulte LICENSE.

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

Parte da Especificação Generativa

Uma ferramenta gratuita 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 o código correto a partir dela, e um harness a verifica contra um sistema ao vivo.

• 📄 White paper (acesso aberto): https://doi.org/10.5281/zenodo.21726017
• 🧭 Comece aqui — método, ferramentas, depoimentos: https://pragmaworks.dev
• 🔨 The Forge — workshop prático de GS de 2 dias para sua equipe: https://forgeworkshop.dev