codeindex

Un motor de inteligencia estructural de código que se ejecuta como servidor MCP para agentes de codificación con IA.

Indexa tu base de código con tree-sitter (más de 40 lenguajes), construye un índice de texto completo por trigramas, un índice invertido de palabras y un grafo de dependencias — y los expone a través de 16 herramientas MCP.

 ┌─────────────┐   MCP (stdio)   ┌───────────┐            ┌──────────────────┐
 │  AI Agent   │ ◄─────────────► │ codeindex │  socket    │ codeindex daemon │
 │ (Claude,    │ 16 tools,       │  (relay)  │ ◄────────► │  one per         │
 │  Cursor…)   │ JSON-RPC        └───────────┘            │  workspace       │
 └─────────────┘                                          └────────┬─────────┘
 ┌─────────────┐   MCP (stdio)   ┌───────────┐                     │
 │  AI Agent   │ ◄─────────────► │ codeindex │ ◄───────────────────┘
 │  (session 2)│                 │  (relay)  │   tree-sitter parse (40+ langs)
 └─────────────┘                 └───────────┘   trigram + word index
                                                 dependency graph
                                                 one file watcher
                                                 snapshot persistence

Cada sesión en un repositorio habla MCP stdio simple, como antes. Detrás de eso, comparten un único índice: el árbol se analiza una vez, se observa una vez y se escribe una vez, sin importar cuántos agentes estén conectados. Ocho sesiones en un repositorio solían ser ocho copias del mismo índice, ocho observadores de archivos y ocho escritores de la misma instantánea; medido en un proyecto de 720 archivos, cada sesión pasó de 87 MB a 7 MB, contra un único daemon compartido de 77 MB.

Por qué

Los agentes de codificación con IA gastan tokens leyendo archivos completos. codeindex responde preguntas estructurales — esquemas de símbolos, definiciones, llamadores, radio de explosión, cadenas de dependencias — en unos pocos cientos de tokens en lugar de miles.

Una llamada a plan_change devuelve: dónde se define un símbolo, cada sitio de llamada, el rol arquitectónico del archivo (módulo dios / núcleo estable / isla / controlador), literales codificados para revisar y el radio de explosión transitivo completo si el archivo cambia.

Inicio rápido

El camino más corto, si tienes Node 18+. Nada más que instalar, sin clave, sin configuración — el paquete es un envoltorio de 4 KB que obtiene el binario para tu plataforma y lo verifica contra las sumas de verificación publicadas:

claude mcp add codeindex -- npx -y @munhq/codeindex

¿Sin Node, o quieres también la habilidad y el hook?

# Prebuilt binary + skill + MCP registration, in one command
curl -fsSL https://raw.githubusercontent.com/munhq/codeindex/main/install.sh | sh

# Or build from source:
cd zig && ./fetch-vendor.sh && zig build -Doptimize=ReleaseFast

Docker, para hosts que instalan servidores MCP como imágenes. El espacio de trabajo está montado en modo solo lectura; codeindex nunca escribe en él:

docker run -i --rm -v "$PWD:/workspace:ro" munhq/codeindex

Regístrate con tu agente de IA:

# Claude Code — the plugin is the one-step path. It ships the skill, both
# routing hooks and the MCP server together, and its launcher finds or fetches
# the binary.
claude plugin marketplace add munhq/codeindex
claude plugin install codeindex@codeindex

# Without the plugin (or for a different MCP client), register the binary
# directly. Do not do both: two registrations mean two servers, two copies of
# every tool schema, and two writers on one snapshot. install.sh detects the
# plugin and skips this step when it is present.
claude mcp add -s user codeindex -- ~/.local/bin/codeindex --mcp

# Cursor / Claude Desktop / other MCP clients: add to your config
{
  "mcpServers": {
    "codeindex": {
      "command": "npx",
      "args": ["-y", "@munhq/codeindex"]
    }
  }
}

Cada listado apunta al mismo servidor: npm @munhq/codeindex, el registro oficial de MCP como io.github.munhq/codeindex y Smithery como munhq/codeindex.

La próxima vez que tu agente se inicie, codeindex indexa tu proyecto en segundo plano y sirve consultas estructurales.

Herramientas MCP

Herramienta	Qué hace
status	Estadísticas del índice: número de archivos, número de símbolos, estado de indexación, % de ahorro de tokens, el workspace indexado y si un watcher está activo
search	Búsqueda de texto completo acelerada por trigramas en todos los archivos indexados
find_symbol	Encuentra definiciones de símbolos (funciones, estructuras, clases…) por nombre
find_word	Búsqueda exacta de palabras/identificadores en el índice invertido de palabras
find_callers	Sitios de llamada de un símbolo, cada uno con la función que lo contiene. Coincide por nombre, por lo que se incluye una definición con el mismo nombre en otro lugar
get_outline	Esquema estructural de un archivo (símbolos, recuentos de líneas)
get_tree	Árbol de directorios con metadatos de archivos
get_imports	Qué archivos importa/de los que depende un archivo dado
get_imported_by	Dependencias inversas — quién importa este archivo
get_change_impact	Radio de explosión transitivo: qué se rompe si un archivo cambia
plan_change	Plan de refactorización completo para un símbolo o archivo — definiciones, llamadores, rol del archivo, literales, radio de explosión
get_hot_files	Archivos modificados recientemente ordenados por actualidad
read_file	Lee el contenido de un archivo con rango de líneas opcional
read_symbol	Lee solo el código fuente de un símbolo (con líneas de contexto opcionales)
index_workspace	Indexa o re-indexa un directorio de espacio de trabajo
analyze	Ejecuta uno de los 22 análisis de código (ver más abajo)

Análisis (herramienta analyze)

Análisis	Qué encuentra
security	Secretos codificados, patrones de inyección SQL, bloques inseguros, uso de eval
dead_code	Símbolos que nada nombra fuera de su propia definición, separados de la API pública no utilizada de un paquete de biblioteca
unwrap_audit	Sitios .unwrap() / expect / panic! (Rust), clasificados por si un manejador de solicitudes, un bucle o main los alcanza
test_coverage	Archivos sin cobertura de pruebas
architecture	Olores arquitectónicos — módulos dios, dependencias circulares, islas
crossref	Referencias de símbolos entre archivos
type_drift	Discrepancias de firmas de tipos entre módulos
db_schema	Tablas que crean las migraciones que ningún código nombra, y modelos ORM SQL que ninguna migración crea
migration_parity	Migraciones faltantes para cambios de esquema
manifest_compliance	Problemas de cumplimiento de package.json / Cargo.toml / go.mod
literal_scan	URLs, IPs, puertos, rutas absolutas, TODOs codificados
coupling	Métricas de acoplamiento de módulos
cycles	Detección de dependencias circulares
duplication	Funciones libres reinventadas — el mismo trabajo escrito dos veces
clones	Cuerpos de funciones copiados y pegados, ignorando nombres y espacios en blanco
spawn_scan	Un intérprete iniciado en un bucle o un temporizador, entre archivos, clasificado por costo de inicio por tasa de generación
deps	Inventario de dependencias — versiones duplicadas, crates sin referencia, crates de un solo uso
leak_shapes	Formas que tiene una fuga, cada una emparejada con la serie de tiempo de ejecución que la decide
logic_shapes	Una constante de bytes fija contra el límite de memoria de la unidad que la despliega, y réplicas × tamaño del grupo contra la capacidad de conexión de un pooler
call_cost	Bucles sobre filas clasificados por las idas y vueltas de base de datos y HTTP que cuesta cada elemento, contados a través del grafo de llamadas
field_contention	Un campo de estado declarado escrito por dos o más propietarios
health	Resumen de los análisis anteriores en un informe de salud del índice

Lenguajes compatibles

Más de 40 lenguajes vía tree-sitter: Rust, Python, TypeScript/TSX, Go, Zig, C, C++, Java, Ruby, Bash, C#, Kotlin, Lua, Scala, Elixir, R, Swift, Dart, Haskell, TOML, JSON, YAML, HTML, CSS, SCSS, SQL, HCL, Dockerfile, Markdown, Nix, Make y más.

Configuración

codeindex --mcp                          # Run as MCP server (stdio)
codeindex --mcp --no-daemon              # ...without sharing the workspace daemon
codeindex --daemon-idle-secs 0           # Keep the daemon resident indefinitely
codeindex --workspace ./my-project       # Index a specific directory
codeindex --project-id my-project        # Project identifier
codeindex -v                             # Print version
codeindex -h                             # Print help

# Environment variables
CODEINDEX_WORKSPACE=/path/to/project     # Same as --workspace
CODEINDEX_PROJECT_ID=my-project          # Same as --project-id

Cómo lograr que se use

Un servidor que se registra sin decirle a un agente cuándo recurrir a él permanece inactivo, y un índice inactivo no ahorra nada por baratas que sean sus llamadas. El plugin incluye tres cosas para eso, en el orden en que actúan:

1. Un resumen de SessionStart. Alrededor de 240 tokens, una vez por sesión, en un repositorio que contiene archivos fuente: codeindex está activo, y aquí está la herramienta para cada tipo de pregunta de código. Llega antes de que el agente haya elegido una herramienta, que es el único momento que puede cambiar la primera elección.
2. Una pista de PreToolUse. Se activa en la 1.ª, 8.ª y 25.ª pregunta de código de una sesión, cuando un escaneo está a punto de responder algo que el índice responde mejor, y nombra la herramienta para esa pregunta exacta. Coincide con Bash así como con Read/Grep/Glob, porque un modo de permisos que enruta el trabajo de archivos a través del shell es donde ocurren la mayoría de los escaneos.
3. La habilidad, que el modelo carga cuando decide que la tarea lo requiere.

El consejo pierde ante el hábito, por lo que el caso estrecho donde el índice es estrictamente mejor se rechaza en lugar de discutirse: una búsqueda de identificador que es toda la línea de comando, en un proyecto que se ha indexado antes. Nunca rechaza una lectura de archivo — los bytes se requieren antes de un Edit — nunca rechaza una línea que también compila o prueba, y deja de rechazar después de tres veces en una sesión, por lo que nunca puede ser la razón por la que una sesión no puede continuar.

Eso está activado por defecto, y es un interruptor para apagarlo — sin archivo que editar a mano. Es una opción del plugin, por lo que /plugin lo muestra como "Rechazar un escaneo que el índice responde mejor" y Claude Code pasa tu respuesta al hook. Fuera del plugin, o para una sola sesión, CODEINDEX_ENFORCE=0 en el entorno anula la opción y CODEINDEX_ENFORCE=1 la restaura.

Mide el efecto en lugar de asumirlo: python3 plugin/measure_routing.py cuenta, por sesión, cuántas preguntas de código fueron a un escaneo y cuántas fueron a el índice, en todos los hogares de Claude Code en la máquina.

Qué árbol se indexa

En modo --mcp, el directorio de trabajo pertenece al cliente, no a ti, y regularmente no es tu proyecto: Claude Code lanza el servidor MCP de un plugin desde el propio directorio del plugin y un servidor de ámbito de usuario desde su directorio de configuración. Por lo tanto, el espacio de trabajo se resuelve en este orden, y la primera respuesta utilizable gana:

1. --workspace o CODEINDEX_WORKSPACE. Una respuesta explícita nunca se anula.
2. CLAUDE_PROJECT_DIR, que Claude Code establece en cada servidor MCP que genera.
3. El directorio de lanzamiento, subiendo en busca de un marcador .git, package.json, Cargo.toml, go.mod, build.zig o pyproject.toml.
4. El roots del cliente. El servidor los solicita en el apretón de manos siempre que la raíz anterior fue una suposición, y adopta uno cuando la suposición fue rechazada o cae fuera de cada raíz que el cliente informa. notifications/roots/list_changed también se respeta, por lo que un directorio agregado con --add-dir aún puede rescatar una sesión.

status informa la raíz efectiva como workspace, y si un observador de archivos está ejecutándose como watcher. Verifícalos cuando un resultado parezca vacío: un índice del árbol equivocado responde cada pregunta con la misma confianza que el correcto.

Se niega a indexar todo tu directorio de inicio, la raíz del sistema de archivos o una carpeta que simplemente contiene varios repositorios independientes. Un espacio de trabajo rechazado responde cada consulta con la razón y la única llamada que lo soluciona — index_workspace con la ruta del proyecto — en lugar de con "sin resultados".

Arquitectura

• Analizador: tree-sitter con más de 40 gramáticas, compilado en un solo binario
• Índice: índice de trigramas para búsqueda de texto difuso + índice invertido de palabras para búsqueda exacta de identificadores
• Grafo de dependencias: resolución de importaciones a nivel de archivo con aristas directas e inversas
• Almacén de versiones: rastrea cambios de archivos con números de secuencia para actualizaciones incrementales
• Observador en vivo: re-indexa al crear/modificar/eliminar archivos (hilo en segundo plano en modo MCP). inotify en Linux; un recorrido de sondeo en macOS y Windows, que compara mtime y tamaño cada un par de segundos. status informa qué backend está activo como watcher_backend.
• Instantánea: persiste el índice completo en .codeindex.json, por lo que un reinicio carga la instantánea en lugar de re-indexar
• Servidor MCP: JSON-RPC sobre stdio, implementa el protocolo MCP 2024-11-05
• Daemon de espacio de trabajo: la primera sesión en un repositorio inicia un daemon en segundo plano y se convierte en un relé hacia él; las sesiones posteriores solo se conectan. Un socket de dominio Unix en Linux, macOS y Windows 10 1803+, en $XDG_RUNTIME_DIR/codeindex (o un directorio por usuario bajo TMPDIR), nombrado por un hash del espacio de trabajo y la versión del binario — por lo que un binario reconstruido nunca hereda el daemon de la versión anterior. Se cierra después de 15 minutos sin ninguna sesión conectada. Cualquier cosa que salga mal cae en la indexación en proceso, que es lo que sucedía antes de que existiera el daemon. Apágalo con --no-daemon.

Soporte de plataformas

Cada fila es construida por CI y sus pruebas se ejecutan en esa plataforma, excepto donde se indica. status informa el backend del observador en vivo para que nunca sea una suposición.

	binario	pruebas en CI	observador	install.sh	plugin
Linux x86_64	Sí	Sí	inotify	Sí	Sí
Linux aarch64	Sí	compilación cruzada	inotify	Sí	Sí
macOS aarch64	Sí	Sí	sondeo	Sí	Sí
macOS x86_64	Sí	compilación cruzada	sondeo	Sí	Sí
Windows x86_64	Sí	Sí	sondeo	necesita un shell	ver abajo
Windows aarch64	Sí	compilación cruzada	sondeo	necesita un shell	ver abajo
En Windows, install.sh y el lanzador del plugin son scripts de shell, por lo que
necesitan Git Bash, MSYS2 o Cygwin — lo detectan y resuelven el recurso .exe
correcto. El plugin registra su servidor a través de ese lanzador, por lo que un
Claude Code nativo de Windows sin shell debería registrar el binario directamente:

claude mcp add -s user codeindex -- C:\path\to\codeindex.exe --mcp

Nada aquí está firmado o notarizado. En macOS, un binario obtenido con curl se ejecuta sin un aviso de Gatekeeper; uno descargado a través de un navegador está en cuarentena, y xattr -d com.apple.quarantine codeindex lo limpia.

Compilación desde el código fuente

Requiere Zig 0.16.0.

cd zig
./fetch-vendor.sh    # Clone tree-sitter + 40 grammar repos
zig build -Doptimize=ReleaseFast
# Binary: zig/zig-out/bin/codeindex

Ejecuta las pruebas:

cd zig && zig build test-bin && ./zig-out/bin/test

zig build test enruta los resultados a través del protocolo IPC del ejecutor de compilación en stdout, que los fuentes C de tree-sitter vinculados corrompen mediante sus rutas de depuración printf. Compilar el binario de prueba y ejecutarlo directamente son las mismas pruebas sin ese protocolo en el camino.

Cómo se compara

	codeindex	ast-grep	ctags	LSIF	Sourcegraph
Nativo MCP	Sí	No	No	No	No
Eficiente en tokens	Sí (esquemas, no archivos completos)	No	Parcial	Sí	Sí
Binario único	Sí	Sí	Sí	No	No (servidor)
Vigilante en vivo	Sí (inotify / sondeo)	No	No	No	No
Grafo de dependencias	Sí	No	No	Sí	Sí
Radio de impacto	Sí (transitivo)	No	No	No	Parcial
Planificador de refactorización	Sí (plan_change)	No	No	No	No
Idiomas	40+	20+	50+	Varía	Varía

Se complementa con chat-recall

codeindex responde preguntas sobre el código frente a ti. chat-recall responde preguntas sobre el trabajo que ya hiciste — indexa tus sesiones de Claude Code, Gemini CLI, Codex, OpenCode, Antigravity y Cursor en un historial buscable y lo expone también a través de MCP.

Juntos cubren ambas mitades de lo que un agente olvida: codeindex evita que vuelva a leer archivos que podría haber esquematizado, y chat-recall evita que rehaga trabajo que ya terminó. chat-recall detecta un binario de codeindex en tu PATH y registra cuatro herramientas adicionales de inteligencia de código cuando lo encuentra — ninguno requiere del otro.

Licencia

MIT. Consulta LICENSE.