CodeSeeker

CodeSeeker

Búsqueda híbrida de cuatro capas y grafo de conocimiento para asistentes de codificación con IA.
Fusión de BM25 + embeddings vectoriales + resúmenes de directorio RAPTOR + expansión de grafo — combinados en una única herramienta MCP que da 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.
Un solo comando para indexar; el plugin de Claude Code lo mantiene sincronizado a partir de ahí.

Creado por PragmaWorks como parte de Generative Specification — la disciplina para construir software con IA que no se desvía. Dos servidores MCP hermanos se componen con este, cada uno resolviendo una mitad diferente del mismo problema:

Son independientes: instala uno, o los tres.

Cuándo dejas de necesitar esto

CodeSeeker resuelve un problema de recuperación, y ese problema se está reduciendo.

Si ejecutas un bucle dirigido por especificaciones con un harness real — una especificación lo bastante precisa como para que un modelo sin estado derive de ella, y puertas de calidad que verifiquen el resultado contra un sistema en vivo — o uno dirigido por intención, tu asistente recibe la estructura que de otro modo tendría que ir a buscar. Una herramienta centinela que enruta acciones en lugar de extenderse por una docena de endpoints elimina otra parte de la búsqueda. Los modelos de frontera con mejor navegación y mayor contexto efectivo eliminan más. Más allá de cierto punto, la búsqueda semántica sobre tu propio código deja de ser el cuello de botella, y este servidor se convierte en algo que podrías desinstalar sin notarlo.

Ese es el resultado previsto, no un defecto: un método que funciona debería hacer innecesario su propio andamiaje. Sin embargo, la mayoría de los equipos no empiezan ahí, y hasta que el proceso esté implementado, CodeSeeker es el sustituto más barato — un comando en lugar de una disciplina.

Si prefieres tener el proceso en lugar del sustituto, empieza con la guía de campo: Generative Specification — Guía de campo (PDF).

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 están 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 empieza desde cero

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

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 impulsa la acción graph, 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 maneje errores así" → búsqueda de patrones semánticos
• "¿Qué enfoque de validación usa 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 omite:

• Cadenas directas de importación/exportación
• Jerarquías de herencia de clases
• Qué archivos dependen realmente de cuáles

Instalación

Recomendado: instala una vez, configura una vez

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

--scope user lo hace disponible en cada proyecto que abras, no solo en el actual.

Por qué global en lugar de npx -y: en una máquina que nunca ha visto el paquete, npx lo descarga y compila dependencias nativas antes de que el servidor pueda responder, lo que midió 13.7 segundos hasta un handshake MCP completado. Los clientes que se rinden antes lo reportan como un fallo de conexión. Una instalación global responde en 759 ms — la descarga ocurre una vez, en un momento en que lo esperas.

npx (sin instalación)

Portátil, y está bien una vez que el paquete está en caché. Espera un primer arranque lento.

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

Añade esto a tu archivo de configuración MCP (ver abajo para ubicaciones por cliente) y reinicia tu editor.

Otros editores

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

🔌 Plugin de Claude Code

Para usuarios de Claude Code CLI — añade hooks de auto-sincronización 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"
}

✅ Verificación

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

Deberías ver una única herramienta llamada codeseeker. Eso es intencional: una herramienta con una clave de enrutamiento action mantiene bajo el overhead de tokens por solicitud (ADR-002). Las acciones son search, sym, graph, analyze y index.

Opciones Avanzadas de Instalación

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

Lo Que Obtienes

CodeSeeker expone una herramienta MCP, codeseeker. Eliges el comportamiento con action y rellenas solo el grupo de parámetros anidados correspondiente:

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

Pasa siempre project (la raíz absoluta del proyecto) — un servidor MCP no puede detectar tu directorio de trabajo.

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

Cómo Funciona la Indexación

No tienes que indexar nada primero. Buscar en un proyecto que CodeSeeker nunca ha visto inicia el índice automáticamente y lo dice. La indexación se ejecuta en segundo plano, así que la llamada devuelve de inmediato en lugar de bloquear a tu asistente:

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

Así que la primera pregunta que haces a un proyecto nuevo responde con "indexación iniciada, reintenta en breve" en lugar de con resultados. Un proyecto pequeño está listo en un par de segundos; uno grande tarda varios minutos. Comprueba con index({op:"status"}) en lugar de adivinar.

Aún puedes indexar deliberadamente, y vale la pena hacerlo para un repositorio grande para que la espera ocurra cuando la esperas:

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

codeseeker init          # or, from the CLI

name es lo único que un init explícito te da que el automático no puede saber — de lo contrario, el proyecto se registra bajo su nombre de directorio.

Mantener el índice actualizado

El índice es una instantánea. Nada vigila tu sistema de archivos, así que después de que los archivos cambien hay tres formas de que vuelva a estar al día:

Sin el plugin, un índice que se desvía seguirá devolviendo resultados; simplemente serán del código tal como era. La señal stale_index es lo que lo saca a la superficie.

Investigación de Calidad de Búsqueda

npm run build
node scripts/real-bench.js

Estándares de codificación auto-detectados

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

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 encontrando código duplicado y detectando código muerto.

Encontrar código duplicado

Pide a Claude que encuentre 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 lenguajes

Cada lenguaje está indexado y es buscable — la fragmentación y los embeddings no dependen de un parser. Lo que cambia el parser es el grafo de conocimiento: con qué precisión sabe CodeSeeker qué símbolo es una declaración y qué depende de qué.

La extracción con regex es una limitación real, no una versión más pequeña de lo mismo. Encuentra declaraciones por forma, por lo que omite cualquier cosa escrita de forma inusual y no puede distinguir una declaración de una llamada. Las aristas de importación siguen siendo fiables para TypeScript y JavaScript, donde Babel las analiza; las aristas de llamadas son heurísticas en todas partes.

Las calificaciones anteriores están medidas, no afirmadas. scripts/corpus-bench.js indexa siete proyectos reales y scripts/graph-quality.js informa cuánto de cada grafo resultante es plausiblemente una declaración real. Java no tiene calificación propia porque ningún proyecto de Java está en ese corpus; comparte la ruta de código Tree-sitter de Python, y eso es todo lo que podemos afirmar.

Medido en las cuatro implementaciones de RealWorld Conduit — la misma aplicación escrita cuatro veces, por lo que una brecha entre ellas es manejo de lenguaje y no dificultad de tarea — el rango recíproco medio sobre 30 consultas etiquetadas es TypeScript 83.3%, Python 81.5%, JavaScript 77.1%, C# 70.5%.

Añadir un parser para tu lenguaje

Si tu proyecto es principalmente Go, Rust, C++ o Ruby, puedes instalar la gramática Tree-sitter para él:

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

Luego pregunta a tu asistente, o ejecuta:

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

La respuesta marca cada parser con wired: true o wired: false. Solo un parser marcado como wired: true es consumido por el constructor de grafos — instalar uno marcado como false no cambia nada hoy, y la respuesta lo dice en lugar de dejarte descubrirlo al no notar una mejora.

Actualmente conectados: TypeScript, JavaScript, Python, Java, C#. Los demás son honestos false. Conectar uno es un cambio pequeño y autocontenido — un parser que implemente ILanguageParser registrado en extensionToParser (src/mcp/indexing-service.ts) — y las contribuciones son bienvenidas. scripts/graph-quality.js mide si un nuevo parser realmente mejoró el grafo, por lo que la mejora es demostrable en lugar de asumida.

Mantener el índice sincronizado

Con el plugin de Claude Code

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

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 codeseeker({action:"index", index:{op:"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 de RAPTOR, etapas del pipeline, niveles de confianza del 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. Comprueba la sintaxis del archivo de configuración MCP (JSON válido, sin comas finales)
3. Reinicia completamente tu editor/aplicación de Claude
4. Comprueba que Node.js esté instalado: node --version (se necesita v18+)

El indexado parece lento

El indexado inicial de proyectos grandes (50K+ archivos) puede tardar 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, comprueba 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. Comprueba 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 compatibles

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 Apache 2.0. Consulta LICENSE y NOTICE.

Gratis para cualquier uso, incluido el comercial — sin límites de tamaño de empresa ni ingresos. Apache-2.0 añade una concesión de patente explícita sobre MIT, que es por lo que es la elección aquí.

Ejecutar CodeSeeker en un equipo

Todo lo anterior es la configuración local de un solo desarrollador: el índice vive en .codeseeker/ en tu máquina y nunca sale de ella.

Existe un despliegue centralizado para equipos — un índice compartido sobre los repositorios de tu organización (PostgreSQL + pgvector, Neo4j), para que los ingenieros no paguen cada uno por reindexar el mismo código, y para que el grafo abarque los límites de los servicios en lugar de detenerse en un solo repositorio. También saca a la superficie lo que la herramienta local estructuralmente no puede: cómo se distribuye realmente la comprensión del código en un codebase y dónde están las brechas de conocimiento.

Si eso es útil para tu equipo, ponte en contacto: https://pragmaworks.dev

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

Parte de Generative Specification

Una herramienta Apache-2.0 detrás de Generative Specification (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 de ella, y un arnés la verifica contra un sistema en vivo.

• 📄 Documento técnico (acceso abierto): https://doi.org/10.5281/zenodo.21726017
• 📕 Guía de campo — la introducción práctica y breve: https://github.com/jghiringhelli/generative-specification/blob/main/docs/white-paper/GenerativeSpecification_FieldGuide.pdf
• 🧭 Empieza aquí — método, herramientas, testimonios: https://pragmaworks.dev
• 🔨 La Forja — taller práctico de GS de 2 días para tu equipo: https://forgeworkshop.dev