CodeSeeker

Búsqueda híbrida de cuatro capas y grafo de conocimiento para asistentes de codificación de IA.
BM25 + embeddings vectoriales + resúmenes de directorios RAPTOR + expansión de grafo — fusionados en una sola herramienta MCP que brinda a Claude, Copilot y Cursor una comprensión real de tu base de código.

Funciona con Claude Code, GitHub Copilot (VS Code 1.99+), Cursor, Windsurf y Claude Desktop.
Configuración cero — indexa al primer uso, se mantiene sincronizado automáticamente.

El Problema

Los asistentes de IA son editores potentes, pero navegan por el código como un turista:

• Grep encuentra texto — no significado. "find authentication logic" devuelve todos los archivos que contienen la palabra "auth"

• Las lecturas de archivos son aisladas — Claude ve un archivo pero no sus dependencias, llamadores, ni los patrones que tu equipo estableció

• Sin memoria de tu proyecto — cada sesión comienza desde cero

CodeSeeker soluciona esto. Indexa tu base de código una vez y proporciona a los asistentes de IA un grafo de conocimiento consultable que pueden usar en cada turno.

Related MCP server: total-recall

Cómo Funciona

Un pipeline de 4 etapas se ejecuta en 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), ...

El grafo de conocimiento se construye a partir de importaciones analizadas por AST en el momento de la indexación. Es lo que potencia analyze dependencies, la detección de código muerto y la expansión de grafo en cada búsqueda.

Qué Lo Hace Diferente

Lo que las herramientas LSP no pueden hacer:

• "Encuentra código que maneja errores como este" → búsqueda de patrones semánticos

• "¿Qué enfoque de validación utiliza este proyecto?" → estándares de codificación auto-detectados

• "Muéstrame todo lo relacionado con autenticación" → recorrido de grafo a través de dependencias indirectas

Lo que la búsqueda solo vectorial pierde:

• Cadenas directas de importación/exportación

• Jerarquías de herencia de clases

• Qué archivos dependen realmente de cuáles

Instalación

Recomendado: npx (sin instalación necesaria)

La forma estándar de configurar cualquier servidor MCP — no requiere instalación global:

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

Agrega esto a tu archivo de configuración MCP (consulta abajo para las ubicaciones por cliente) y reinicia tu editor.

Instalación global con npm

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

🔌 Plugin para Claude Code

Para usuarios de Claude Code CLI — agrega hooks de sincronización automática y 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"
}

✅ Verificar

Pregunta a tu asistente de IA: "¿Qué herramientas de CodeSeeker tienes?"

Deberías ver: search, analyze, index — las tres herramientas de CodeSeeker.

Opciones Avanzadas de Instalación

El JSON de configuración MCP es el mismo para todos los clientes — solo cambia la ubicación del archivo:

{
  "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?"

Qué Obtienes

Una vez configurado, Claude tiene acceso a estas herramientas MCP (usadas automáticamente):

No invocas estas manualmente—Claude las usa automáticamente al buscar código o analizar relaciones.

Cómo FFunciona la Indexación

No necesitas indexar manualmente. Cuando Claude usa cualquier herramienta de CodeSeeker, la herramienta verifica automáticamente si el proyecto está indexado. Si no lo está, indexa en el primer uso.

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

La primera búsqueda en un nuevo proyecto toma de 30 segundos a varios minutos (dependiendo del tamaño). Las búsquedas posteriores son instantáneas.

Investigación de Calidad de Búsqueda

Configuración

18 consultas etiquetadas manualmente en dos bases de código reales:

Cada consulta tiene uno o más objetivos mustFind (nombres base de archivo exactos) y objetivos opcionales mustNotFind (verificación de fuga de alcance). Las consultas se ejecutaron en un índice real construido desde la fuente — embeddings reales de Xenova, grafo real, nodos RAPTOR L2 reales — para reflejar las condiciones de producción.

Métricas: MRR (Mean Reciprocal Rank), P@1 (Precisión en 1), R@5 (Recall en 5), F1@3.

Resultados de ablación

Lo que cada capa realmente hace

BM25 + fusión de embeddings (RRF)
El caballo de batalla. Maneja ~94% de la calidad de clasificación por sí solo. BM25 captura nombres de símbolos exactos y tokens camelCase; los embeddings vectoriales capturan similitud semántica cuando los nombres difieren. Fusionado con Reciprocal Rank Fusion para combinar ambas señales sin ajuste manual de pesos.

RAPTOR (resúmenes jerárquicos de directorios)
Genera nodos de embedding por directorio mediante promedio de todos los embeddings de archivos en una carpeta. Actúa como un postfiltro: cuando un resumen de directorio puntúa ≥ 0.5 contra la consulta, los resultados se limitan a los archivos de ese directorio. Contribución medida: +0.3% MRR en consultas de símbolos. Actúa de forma conservadora — solo cuando el directorio es una coincidencia obvia. Su verdadero valor está en consultas abstractas ("¿qué hace el módulo de pagos?") que no aparecen en este benchmark; para esas consultas, evita la dispersión amplia por toda la base de código.

Grafo de conocimiento (aristas de importación/dependencia)
Conectividad media: 20,8 aristas archivo→archivo por nodo en los codebases de TS y C#. Impacto de ranking medido: ±0 % MRR para expansión de 1 salto. El grafo no mueve el MRR porque la capa semántica ya encuentra los archivos correctos — los vecinos del grafo suelen estar ya en el top-15. Su valor es estructural: la acción analyze dependencies y el tipo de búsqueda explícito graph le dan a Claude cadenas de importación transitables, jerarquías de herencia y rutas de dependencia que los embeddings por sí solos no pueden proporcionar.

Puntuación de refuerzo/penalización por tipo
Los archivos fuente reciben un refuerzo de +0,10; los archivos de prueba reciben una penalización de −0,15; los archivos de bloqueo y documentación reciben una penalización de −0,05. Sin esto, integration.test.ts se clasificaría por encima de dag-engine.ts para consultas de símbolos exactos porque los archivos de prueba importan y ejercitan cada símbolo en el código fuente. La penalización corrige esto sin eliminar los archivos de prueba de los resultados.

Corrección de exclusión de directorios en monorepos
El cambio de mayor impacto en v1.12.0: eliminar packages/ de la lista de exclusiones predeterminada. Para monorepos pnpm/yarn/lerna donde todo el código fuente vive bajo packages/, esta exclusión estaba eliminando silenciosamente todos los archivos fuente. Efecto: 10 % → 72 % MRR en el benchmark del monorepo Conclave.

Limitaciones conocidas

Script de benchmark

Reproducir con:

npm run build
node scripts/real-bench.js

Requiere que C:\workspace\claude\conclave y C:\workspace\ImperialCommander2 estén presentes localmente (o actualizar las rutas en scripts/real-bench.js).

Estándares de Codificación Detectados Automáticamente

CodeSeeker analiza tu codebase y extrae patrones:

{
  "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
    }
  }
}

Categorías de patrones detectados:

• validación: Zod, Yup, Joi, validator.js, regex personalizado

• manejo de errores: respuestas de error de API, patrones try-catch, clases Error personalizadas

• registro: Console, Winston, Bunyan, registro estructurado

• pruebas: configuración de Jest/Vitest, patrones de aserción

• patrones-react: Hooks (useState, useEffect, useMemo, useCallback, useRef)

• gestión-de-estado: Redux Toolkit, Zustand, React Context, TanStack Query

• patrones-api: Fetch, Axios, rutas Express, rutas API de Next.js

Cuando Claude escribe código nuevo, sigue tus convenciones existentes en lugar de inventar otras nuevas.

Gestión de Exclusiones de Índice

Si Claude nota archivos que no deberían indexarse (como la carpeta Library de Unity, salidas de compilación o archivos generados), puede excluirlos dinámicamente:

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

Las exclusiones se persisten en .codeseeker/exclusions.json y se respetan automáticamente durante el reindexado.

Herramientas de Limpieza de Código

CodeSeeker te ayuda a mantener un codebase limpio al encontrar código duplicado y detectar código muerto.

Encontrar Código Duplicado

Pide a Claude que busque bloques de código similares que podrían consolidarse:

"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 similitud vectorial para encontrar código semánticamente similar—no solo coincidencias exactas. Detecta:

• Funciones copiadas y pegadas con variaciones menores

• Lógica de validación similar entre archivos

• Patrones repetidos que podrían extraerse en utilidades

Encontrar Código Muerto

Pide a Claude que identifique código no utilizado que pueda eliminarse de forma segura:

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

CodeSeeker analiza el grafo de conocimiento para encontrar:

• Funciones/clases exportadas que nunca se importan

• Funciones internas sin llamadores

• Archivos huérfanos sin dependencias entrantes

Flujo de trabajo de ejemplo:

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?

Soporte de Idiomas

Los analizadores Tree-sitter se instalan automáticamente cuando es necesario.

Mantener el Índice Sincronizado

Con el Plugin de Claude Code

El plugin instala hooks que actualizan el índice automáticamente:

No necesitas hacer nada—el plugin maneja la sincronización automáticamente.

Solo con Servidor MCP (Cursor, Claude Desktop)

• Cambios iniciados por Claude: Claude puede llamar a la herramienta index({action: "sync"})

• Cambios manuales: No se detectan automáticamente—pide a Claude que reindexe periódicamente

Resumen de Sincronización

Cuándo CodeSeeker Ayuda Más

Buena opción:

• Codebases grandes (10K+ archivos) donde Claude tiene dificultades para encontrar código relevante

• Proyectos con patrones establecidos que quieres que Claude siga

• Cadenas de dependencia complejas entre múltiples archivos

• Equipos que quieren código generado por IA consistente

Menos útil:

• Proyectos greenfield con poco código existente

• Scripts de un solo archivo

• Proyectos donde estás cambiando activamente la arquitectura

Arquitectura

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

Todos los datos se almacenan localmente en .codeseeker/. No se requieren servicios externos.

Para equipos grandes (100K+ archivos, índices compartidos), el modo servidor admite PostgreSQL + Neo4j. Consulta Documentación de Almacenamiento.

Para los detalles técnicos completos — fórmulas de puntuación exactas, esquema de herramientas MCP, tipos de aristas del grafo, lógica de umbral RAPTOR, etapas del pipeline, niveles de confianza de análisis — consulta el Manual de Arquitectura Técnica.

Solución de Problemas

El servidor MCP no se conecta

1. Verifica que npm y npx funcionen: npx -y codeseeker --version

2. Revisa la sintaxis del archivo de configuración MCP (JSON válido, sin comas finales)

3. Reinicia tu editor/aplicación de Claude por completo

4. Verifica que Node.js esté instalado: node --version (se necesita v18+)

La indexación parece lenta

La indexación inicial de proyectos grandes (50K+ archivos) puede tardar más de 5 minutos. Los usos posteriores son instantáneos.

Las herramientas no aparecen en Claude

1. Pregunta a Claude: "¿Qué herramientas de CodeSeeker tienes?"

2. Si no aparecen herramientas, verifica que el archivo de configuración MCP exista y tenga la sintaxis correcta

3. Reinicia tu IDE por completo (no solo recargar la ventana)

4. Verifica el estado de conexión MCP de Claude/Copilot en el IDE

¿Sigue atascado?

Abre un issue: GitHub Issues

Documentación

• Guía de Integración - Cómo se conectan todos los componentes

• Arquitectura - Inmersión técnica profunda

• Comandos CLI - Referencia completa de comandos

Plataformas Soportadas

Claude Code y GitHub Copilot comparten el mismo .vscode/mcp.json — configúralo una vez, funciona para ambos.

Soporte

Si CodeSeeker te resulta útil, considera patrocinar el proyecto.

Licencia

Licencia MIT. Consulta LICENSE.

CodeSeeker le da a Claude la comprensión del código que grep y los embeddings por sí solos no pueden proporcionar.

Parte de Especificación Generativa

Una herramienta gratuita detrás de Especificación Generativa (GS) — la disciplina para construir software con IA que no se desvía: redactas una especificación lo suficientemente precisa para que una IA sin estado derive código correcto a partir de ella, y un harness la verifica contra un sistema en vivo.

• 📄 Documento técnico (acceso abierto): https://doi.org/10.5281/zenodo.21726017

• 🧭 Empieza aquí — método, herramientas, testimonios: https://pragmaworks.dev

• 🔨 The Forge — taller práctico de GS de 2 días para tu equipo: https://forgeworkshop.dev