codeix

codeix

codeix.dev · Búsqueda semántica de código rápida para agentes de IA: encuentra símbolos, referencias y llamadores en cualquier base de código.

codeix                 # start MCP server, watch for changes
codeix build           # parse source files, write .codeindex
codeix -r ~/project build  # build from a specific directory

Por qué

Los agentes de codificación de IA gastan la mayor parte de su presupuesto de tokens encontrando código antes de poder trabajar en él. Hacen grep, leen archivos, vuelven a hacer grep, retroceden. En una base de código grande, el agente podría quemar miles de tokens solo para localizar la función correcta, o peor, no encontrarla y alucinar.

Codeix le da al agente un mapa preconstruido de tu base de código. Una consulta estructurada devuelve el nombre del símbolo, archivo, rango de líneas, firma y padre, sin escaneo ni adivinanzas.

Lo que las herramientas existentes hacen mal

Problema	Lo que sucede hoy
Sin estructura	grep encuentra coincidencias de texto, no símbolos. El agente no puede distinguir una definición de función de un comentario que la menciona.
Re-análisis lento	Los indexadores basados en Python re-analizan todo al inicio. En bases de código grandes, esperas.
No compartible	Los índices son cachés locales: efímeros, por máquina. Un nuevo desarrollador o runner de CI empieza desde cero.
Sin composición	¿Monorepo con 10 paquetes? ¿Dependencias con APIs útiles? No hay forma de consultar a través de límites.
La prosa es invisible	TODOs, docstrings, mensajes de error: buscables con grep pero no selectivamente. No puedes buscar solo comentarios sin también coincidir con código.

Lo que codeix hace de manera diferente

• Comprometido con git — el índice es un directorio .codeindex que comprometes con tu código. Clona el repositorio, el índice ya está ahí. Sin re-indexación.
• Compartible — los autores de bibliotecas pueden incluir .codeindex en su paquete npm/PyPI/crates.io. Los consumidores obtienen navegación instantánea de dependencias.
• Componible — el servidor MCP descubre automáticamente los índices de dependencias y los monta. Consulta tu código y tus dependencias en un solo lugar.
• Estructurado para LLMs — los símbolos tienen tipos, firmas, relaciones padre-hijo y rangos de líneas. El agente obtiene exactamente lo que necesita en una sola llamada de herramienta en lugar de armarlo a partir de texto crudo.
• Búsqueda de prosa — search --scope text apunta específicamente a comentarios, docstrings y literales de cadena. Encuentra TODOs, encuentra el mensaje de error que reportó un usuario, encuentra lo que dice el docstring de una función, sin ruido del código.
• Rápido — se construye en segundos, consultas en milisegundos. Rust + tree-sitter + SQLite FTS5 en memoria bajo el capó.

El formato .codeindex

Un formato abierto y portátil para indexación estructurada de código. Archivos JSONL simples que comprometes junto con tu código: diffs amigables con git, legibles por humanos con grep y jq, sin blobs binarios.

.codeindex/
  index.json        # manifest: version, name, languages
  files.jsonl       # one line per source file (path, lang, hash, line count)
  symbols.jsonl     # one line per symbol (functions, classes, imports, with signatures)
  texts.jsonl       # one line per comment, docstring, string literal

Cualquier herramienta que pueda analizar JSON puede consumir un .codeindex. Codeix lo construye usando tree-sitter, y los agentes de IA lo consultan a través de MCP (Protocolo de Contexto de Modelo).

Ejemplo — symbols.jsonl:

{"file":"src/main.py","name":"os","kind":"import","line":[1,1]}
{"file":"src/main.py","name":"Config","kind":"class","line":[22,45]}
{"file":"src/main.py","name":"Config.__init__","kind":"method","line":[23,30],"parent":"Config","sig":"def __init__(self, path: str, debug: bool = False)"}
{"file":"src/main.py","name":"main","kind":"function","line":[48,60],"sig":"def main(args: list[str]) -> int"}

Envía tu índice con tu paquete

Incluye .codeindex en tu paquete y cada desarrollador que dependa de ti obtiene navegación instantánea de tu API, sin configuración ni re-indexación.

Funciona con repositorios Git, npm, PyPI y crates.io.

Herramientas MCP

Siete herramientas, cero configuración. El agente consulta inmediatamente: sin init, sin config, sin refresh.

Herramienta	Qué hace
explore	Explora la estructura del proyecto: metadatos, subproyectos, archivos agrupados por directorio
search	Búsqueda unificada de texto completo en símbolos, archivos y textos (FTS5, clasificado por BM25) con filtros de alcance/tipo/ruta/proyecto
get_file_symbols	Lista todos los símbolos en un archivo
get_children	Obtiene los hijos de una clase/módulo
get_callers	Encuentra todos los lugares que llaman o referencian un símbolo
get_callees	Encuentra todos los símbolos que una función/método llama
flush_index	Vacía los cambios pendientes del índice al disco

Descubrimiento de proyectos

Lanza codeix desde cualquier directorio. Recorre hacia abajo y trata cada directorio que contenga .git/ como un proyecto separado: cada uno obtiene su propio .codeindex.

Funciona uniformemente para repositorios individuales, monorepos, repositorios hermanos y submódulos de git. No se necesita configuración.

Idiomas

Gramáticas de tree-sitter, habilitadas por características en tiempo de compilación:

Idioma	Flag de característica	Por defecto	Extensiones
Python	lang-python	sí	.py .pyi .pyw
Rust	lang-rust	sí	.rs
JavaScript	lang-javascript	sí	.js .mjs .cjs .jsx
TypeScript	lang-typescript	sí	.ts .mts .cts .tsx
Go	lang-go	sí	.go
Java	lang-java	sí	.java
C	lang-c	sí	.c .h
C++	lang-cpp	sí	.cpp .cc .cxx .hpp .hxx
Ruby	lang-ruby	sí	.rb .rake .gemspec
C#	lang-csharp	sí	.cs
Markdown	lang-markdown	sí	.md .markdown

Soporte de Markdown

Los archivos Markdown se analizan para encabezados (tanto ATX # como estilos de subrayado Setext) que se indexan como símbolos section con relaciones jerárquicas padre-hijo, lo que permite la extracción de TOC y la navegación de la estructura del documento.

Los bloques de código delimitados se extraen como entradas de texto code, con su sección contenedora como padre.

Scripts incrustados

Los archivos HTML, Vue, Svelte y Astro se preprocesan para extraer bloques <script> incrustados, que luego se analizan con la gramática de JavaScript o TypeScript:

Formato	Extensiones	Detección de scripts
HTML	.html .htm	etiquetas <script>, con lang="ts" opcional
Vue	.vue	<script> y <script setup>, con lang="ts" opcional
Svelte	.svelte	<script>, con lang="ts" opcional
Astro	.astro	--- frontmatter (siempre TypeScript) + etiquetas <script> opcionales

Los números de línea en el índice apuntan al archivo original, no al bloque de script extraído.

Instalación

# npm / npx — run without installing
npx codeix

# pip / uvx — run without installing
uvx codeix

# Rust
cargo install codeix

# Homebrew
brew install codeix

# Or build from source
git clone https://github.com/montanetech/codeix.git
cd codeix
cargo build --release

Todos los canales instalan el mismo binario único. Sin dependencias de tiempo de ejecución.

Uso

# Build the index for the current project
codeix build

# Build from a specific directory (discovers all git repos below)
codeix -r ~/projects build

# Start MCP server (default command, watches for changes)
codeix

# Or explicitly
codeix serve
codeix serve --no-watch

# Serve from a specific directory
codeix -r ~/projects serve

Configuración del cliente MCP

Agrega a tu configuración de cliente MCP (por ejemplo, Claude Desktop, Cursor):

{
  "mcpServers": {
    "codeix": {
      "command": "codeix"
    }
  }
}

Principios de diseño

• Solo local — sin red, sin claves API, funciona sin conexión y en entornos aislados
• Determinista — la misma fuente siempre produce el mismo índice (diffs limpios)
• Componible — los índices de dependencias se descubren automáticamente y se montan en tiempo de consulta
• Superficie mínima — 7 herramientas de consulta, cero gestión de tuberías

Arquitectura

Consulta docs/architecture.md para el conjunto completo de registros de decisiones de arquitectura.

Licencia

MIT OR Apache-2.0