Acabas de incorporarte a un proyecto con 400.000 líneas de código repartidas en 12.000 archivos. Alguien te pide que arregles el flujo de autenticación. Haces grep -r "auth" y obtienes 847 resultados. La mitad son comentarios. Un tercio son archivos de prueba. Ninguno te dice cómo funciona realmente la autenticación.

Ese era el problema con el que chocábamos constantemente. Y por eso construimos Octocode.

Octocode es una herramienta de productividad para desarrolladores escrita en Rust: búsqueda semántica de código, servidor MCP y kit de herramientas impulsado por IA en un solo binario. Le preguntas "¿cómo funciona la autenticación de usuarios?" en inglés sencillo, y te devuelve los 3-5 archivos que realmente importan con contexto sobre cómo se conectan. Funciona localmente, opera como una herramienta MCP para Claude y Cursor, y convierte tu base de código en un grafo de conocimiento consultable.

Lo usamos todos los días. Es la herramienta detrás de cómo Octomind —nuestro entorno de ejecución para agentes de IA— se construye y se entrega con rapidez por un equipo de dos personas. Es nuestra arma secreta. Y es de código abierto.

Acabamos de lanzar la v0.13.0 con búsqueda de commits, diffs impulsados por IA, releases automáticos, explicación de código y compresión vectorial RaBitQ. Aquí está el panorama completo.

El dolor que lo originó

Construimos mucho software. Múltiples repos, múltiples lenguajes, proyectos que se remontan años atrás. El problema no era escribir código, era encontrar código. Entender qué existía ya antes de escribir algo nuevo.

grep es rápido pero tonto. Encuentra cadenas, no significado. La búsqueda de GitHub es lenta y limitada a repos públicos. ChatGPT pierde el contexto pasados los 128K tokens. Cada vez que nos incorporábamos a un proyecto antiguo, quemábamos horas releyendo archivos que ya habíamos leído hacía seis meses.

La pregunta era simple: ¿y si la búsqueda de código funcionara como funciona tu cerebro? No piensas "encuéntrame la cadena authenticate", piensas "¿cómo funciona el login?". La herramienta debería entender esa diferencia.

Así que construimos una.

grep vs búsqueda octocode

Qué hace Octocode

En su núcleo, Octocode hace cuatro cosas:

1. Búsqueda semántica — Haz preguntas en inglés natural. Convierte tu consulta en un embedding vectorial, lo compara con embeddings de cada fragmento de código en tu proyecto y devuelve los resultados más relevantes semánticamente. No coincidencias de palabras clave: coincidencias de significado.

2. Análisis de la estructura del código — Extrae firmas de funciones, definiciones de clases e interfaces de módulos de cualquier archivo o patrón glob. Entiende qué hace un archivo sin leer cada línea.

3. Grafos de conocimiento (GraphRAG) — Mapea relaciones entre archivos: quién importa qué, qué módulos son hermanos, cómo fluyen los datos por el sistema. Pregunta "¿cómo está conectado el archivo A con el archivo B?" y obtén una respuesta real.

4. Herramientas de desarrollo impulsadas por IA — Diffs semánticos, revisión de código automatizada, mensajes de commit inteligentes, explicación de la base de código y gestión de releases multi-lenguaje. No son herramientas separadas pegadas encima: están construidas sobre el mismo motor de indexado y búsqueda.

Todo esto se expone como un servidor MCP, lo que significa que Claude, Cursor, Windsurf o cualquier asistente de IA compatible con MCP puede usarlo directamente. Tu IA deja de adivinar sobre tu base de código y empieza a saberla.

Cómo lo usamos realmente

Antes de meternos en las funciones, esta no es una herramienta que construimos y olvidamos. Usamos Octocode a diario para construir Octomind, nuestro entorno de ejecución para agentes de IA.

Así es como se ve un día típico para nosotros:

  • Por la mañana: octocode diff --staged para revisar lo que Ava (nuestra colaboradora IA) entregó durante la noche. No 200 líneas de diff, sino un resumen que dice "Se añadió lógica de reintento a la capa de transporte MCP, se refactorizó el manejo de errores en 3 archivos".
  • Antes de un PR: octocode review --staged --focus security detecta cosas que se nos escaparían. Limitadores de tasa eliminados por accidente. Vectores de inyección SQL. Unwraps inseguros en Rust.
  • Hora de commit: octocode commit genera mensajes a partir del diff real. No más commits "fix stuff".
  • Releases: octocode release lee cada commit desde la última etiqueta, decide un incremento de versión, genera un changelog y actualiza los archivos de versión en Cargo.toml, package.json o lo que use tu proyecto.
  • Todo el día: Claude Code usa Octocode como su servidor MCP. Cuando preguntamos "¿cómo funciona el pipeline de embeddings?", Claude busca el código real, lo lee y responde. Sin alucinaciones.

Este es el flujo de trabajo que permite a dos personas y a una IA entregar como un equipo mucho mayor.

La CLI: herramientas de IA para la productividad del desarrollador

Octocode empezó como una herramienta MCP. Pero cuanto más la usábamos, más nos dimos cuenta: esta cosa también necesita funcionar de forma autónoma. No todo sucede dentro de un chat con IA.

octocode search — búsqueda semántica desde tu terminal

# Consulta única
octocode search "how is user authentication implemented"

# Multi-consulta para resultados exhaustivos
octocode search "auth middleware" "JWT token validation" "session management"

# Busca tipos de contenido específicos
octocode search "database migration" --mode code
octocode search "why did we change the API" --mode commits

# Controla el detalle de la salida
octocode search "auth" --detail-level full

La multi-consulta es la función estrella aquí. En lugar de una búsqueda esperando capturarlo todo, lanzas 3-4 consultas relacionadas y obtienes resultados que cubren el panorama completo. El motor deduplica y rerankea entre todas las consultas.

Los niveles de detalle te permiten controlar cuánto código se devuelve: signatures para un escaneo rápido, partial (por defecto) para truncado inteligente, o full para todo.

octocode view — firmas sin el ruido

# Ver todas las firmas de funciones Rust
octocode view "src/**/*.rs"

# Comprobar la interfaz de un módulo específico
octocode view "src/api/*.ts" --md

# Multi-lenguaje a la vez
octocode view "**/*.{rs,ts,py}"

Esta es una de esas funciones que suena simple pero ahorra tiempo real. Estás revisando un PR que toca 8 archivos. En lugar de abrir cada uno y desplazarte, ejecutas octocode view con un glob y obtienes cada firma de función, definición de struct y export de tipo en una sola salida. El modo markdown (--md) lo hace fácil de pegar.

Usamos esto mucho también en el servidor MCP: cuando Claude necesita entender la interfaz de un módulo antes de editarlo, view_signatures le da la estructura sin volcar 2000 líneas de implementación.

octocode diff — el resumen, no el parche

Esto es nuevo en la v0.13. Y ha cambiado cómo revisamos código generado por IA.

# ¿Qué cambió en mi área de staging?
octocode diff --staged

# ¿Qué pasó entre ramas?
octocode diff main..feature-branch

# Enfocarse en preocupaciones específicas
octocode diff --staged --focus security
octocode diff --staged --focus performance

Aquí está por qué esto importa ahora más que nunca. Las herramientas de IA para codificar generan diffs grandes. Una sola sesión de Claude puede tocar 15 archivos a través de 400 líneas. Leer ese diff en bruto lleva 20 minutos. octocode diff lo lee en segundos y te da un resumen: qué cambió, por qué importa, en qué fijarse.

El flag --focus es agudo. Pasa security y marca validaciones eliminadas, endpoints expuestos, secretos hardcodeados. Pasa performance y resalta nuevas asignaciones, llamadas bloqueantes, índices faltantes. Ejecutamos ambos antes de cada merge.

octocode explain — entiende cualquier cosa

# Explicar un archivo específico
octocode explain src/auth/middleware.rs

# Explicar un concepto a través de la base de código
octocode explain "how does the embedding pipeline work"

Apúntalo a un archivo y obtén un desglose estructurado: qué hace, de qué depende, qué depende de él. Apúntalo a un concepto y busca semánticamente, luego sintetiza los resultados en una explicación. Genial para incorporarse a partes desconocidas de una base de código.

octocode review — atrapa lo que los humanos pasan por alto

octocode review --staged
octocode review --focus security --severity high

No es un reemplazo de la revisión humana. Pero consistentemente atrapa cosas que nos saltaríamos: imports sin usar, manejo de errores inconsistente, posibles condiciones de carrera, problemas de seguridad. Ahora lo ejecutamos antes de cada PR. El filtro de severidad evita que sea ruidoso.

octocode commit — mensajes de commit que significan algo

git add .
octocode commit
octocode commit --yes  # omitir confirmación

Analiza los cambios staged, genera un mensaje de commit que realmente describe lo que pasó. No "update files", sino algo como "refactor: extract embedding batch processing into standalone pipeline with retry logic". Algo pequeño, pero suma cuando haces 20 commits al día.

octocode release — releases multi-lenguaje automatizados

octocode release
octocode release --dry-run
octocode release --force-version "2.0.0"

Este es un sleeper. Lee cada commit desde la última etiqueta git, usa un LLM para determinar el incremento de versión correcto (patch, minor o major), genera un changelog estructurado y actualiza los archivos de versión.

La parte multi-lenguaje importa: maneja Cargo.toml (Rust), package.json (Node), composer.json (PHP), pyproject.toml (Python) y go.mod (Go). Si tu proyecto usa múltiples lenguajes, los actualiza todos.

Usamos esto para cada release de Octocode mismo. El changelog v0.13 —con sus funciones categorizadas, mejoras y correcciones— fue generado por octocode release.

octocode stats — chequeo rápido de pulso

octocode stats
octocode stats --format json

Conteos de archivos por lenguaje, conteos de líneas, estado de indexado. Útil para dashboards de CI o simplemente para responder "¿cuán grande es este proyecto?"

Cómo funciona el indexado

Pipeline de indexado de Octocode

Cuando ejecutas octocode index, esto es lo que pasa bajo el capó:

  1. Descubrimiento de archivos — recorre el repo, respeta .gitignore y .noindex, maneja symlinks
  2. Parseo AST — Tree-sitter parsea cada archivo en un árbol de sintaxis abstracta. Así es como Octocode entiende la estructura del código —funciones, clases, imports, exports— no solo texto
  3. Chunking — el código se divide en fragmentos semánticos (configurable, por defecto 2000 bytes con solapamiento)
  4. Embedding — cada fragmento se convierte en un embedding vectorial vía tu proveedor elegido
  5. Almacenamiento — los vectores van a LanceDB con cuantización RaBitQ opcional (~32x de compresión)
  6. GraphRAG — las relaciones entre archivos se extraen y almacenan como un grafo de conocimiento

Todo el pipeline es incremental. Cambia un archivo, y solo ese archivo se reindexa. Cambia de rama, y Octocode rastrea qué necesita actualizarse. Ese es el nuevo indexado delta consciente de ramas en la v0.13.

Proveedores de embeddings

Tú eliges el tuyo:

Nube (requiere clave API):

  • Voyage AI — la mejor calidad para código, 200M tokens gratis/mes (nuestro predeterminado)
  • Jina AI — embeddings de código sólidos
  • Google AI — gemini-embedding-001
  • OpenAI — text-embedding-3-small/large
  • Together AI — distribuido

Local (sin API, sin red):

  • FastEmbed — el más rápido, 384-dim (macOS)
  • HuggingFace — CodeBERT, sentence-transformers (macOS)

Un detalle que importa: Octocode usa recuperación asimétrica. Los embeddings de código y los embeddings de consulta se generan de forma diferente porque "¿cómo funciona la autenticación?" y fn authenticate(token: &str) están relacionados semánticamente pero son estructuralmente diferentes. Esta es una mejora de precisión significativa frente a herramientas que embeben todo de la misma manera.

Cuantización RaBitQ (nueva en la v0.13)

Los vectores son grandes. Un embedding float32 de 1024 dimensiones son 4KB por fragmento. Multiplica por miles de fragmentos y el almacenamiento suma.

RaBitQ comprime vectores ~32x con pérdida de calidad mínima. Para la mayoría de bases de código, no notarás la diferencia en la calidad de búsqueda. Pero tu índice pasa de 100MB a 3MB. Esto importa cuando estás indexando un monorepo.

octocode config --quantization true
octocode index --force  # reindexar con compresión

Recuperación contextual: la mejora del 49%

Esto se basa en la investigación de Recuperación Contextual de Anthropic: una técnica que reduce los fallos de recuperación un 49%, y un 67% cuando se combina con reranking. Implementamos ambos en Octocode.

El problema con los embeddings de código en bruto: una función llamada process() no significa nada en un espacio vectorial. ¿Procesa pagos? ¿Parsea HTML? ¿Comprime imágenes? El modelo de embedding no puede decirlo solo por el nombre de la función.

Octocode resuelve esto en dos niveles.

Nivel 1: Contexto estructural (siempre activo). A cada fragmento se le antepone la ruta del archivo, el lenguaje y los nombres de los símbolos antes de embeber. Así el modelo de embedding ve # File: src/api/auth.rs / # Language: Rust / # Defines: validate_token, refresh_session antes del código real. Esto por sí solo es una gran mejora: el embedding ahora sabe dónde vive el código y qué define.

Nivel 2: Descripciones generadas por LLM (opcional). Cuando se habilita, un LLM lee cada fragmento y escribe una descripción de 1-2 oraciones de lo que hace. El prompt es específico: "escribe lo que hace este código en términos que un desarrollador buscaría". Así process() se convierte en "valida payloads de webhook entrantes de Stripe y los despacha al manejador de pagos correcto".

Esta descripción se antepone al fragmento antes de embeber. El modelo de embedding ahora tiene tanto el código COMO un puente en lenguaje natural hacia él. Ese puente es exactamente lo que cierra la brecha entre cómo buscan los desarrolladores ("¿cómo funcionan los webhooks?") y cómo se escribe el código (fn process(payload: &[u8])).

octocode config --contextual-descriptions true
octocode config --contextual-model "openrouter:openai/gpt-4o-mini"
octocode index --force

Cuesta unos pocos centavos por mil fragmentos con gpt-4o-mini. Por el salto en la calidad de búsqueda, es algo obvio.

Reranking: precisión después del recall

La búsqueda vectorial es buena en recall: encontrar los documentos correctos en un pajar. Pero ¿rankear esos resultados con precisión? Ahí es donde se vuelve difusa. Dos resultados con similitud de 0.82 y 0.79 podrían estar en el orden incorrecto.

Octocode usa un pipeline de recuperación en dos etapas. Primero, la búsqueda vectorial saca los mejores candidatos (red amplia, alto recall). Luego un reranker cross-encoder repuntúa cada resultado mirando el par consulta-documento completo en conjunto. No embeddings separados: la relación real entre tu pregunta y cada fragmento de código.

La investigación muestra que el reranking con cross-encoders mejora la precisión RAG hasta un 40%. En nuestras pruebas, empuja consistentemente el resultado más relevante a la posición #1 en lugar de la posición #3 o #4. La diferencia entre "útil" y "exactamente lo que necesitabas".

El reranker funciona a través de octolib y soporta múltiples proveedores. Añade unos pocos milisegundos a la latencia de búsqueda. Invisible para humanos. Invisible para clientes MCP.

# El reranking está habilitado por defecto cuando hay un proveedor configurado
octocode config --show  # comprobar la configuración del reranker

Combinado con descripciones contextuales, esto le da a Octocode un pipeline de recuperación más cercano a sistemas RAG state-of-the-art que a herramientas tradicionales de búsqueda de código.

GraphRAG: el grafo de conocimiento

Esta es la función que separa a Octocode de "grep semántico".

Cuando habilitas GraphRAG, Octocode construye un grafo donde cada archivo es un nodo y cada relación es una arista. Las relaciones incluyen:

  • imports — el archivo A importa del archivo B
  • sibling_module — archivos en el mismo directorio
  • parent/child_module — jerarquía de directorios

Cada nodo almacena: ruta del archivo, descripción generada por IA, símbolos extraídos, listas de import/export y embeddings vectoriales.

¿Qué puedes hacer con esto?

# Encuentra todos los archivos relacionados con la autenticación
octocode graphrag search --query "authentication system"

# Traza cómo se conectan dos archivos
octocode graphrag find-path --source-id src/api/auth.rs --target-id src/db/users.rs

# Obtén el detalle completo del rol de un archivo
octocode graphrag get-node --node-id src/api/auth.rs

# Ver todas las dependencias de un archivo
octocode graphrag get-relationships --node-id src/api/auth.rs

# Vista general de alto nivel de la base de código
octocode graphrag overview

El comando find-path está infravalorado. "¿Cómo se conecta el módulo de autenticación con la base de datos?". En un proyecto grande, ese camino puede pasar por 4-5 módulos intermedios cuya existencia desconocías. GraphRAG lo encuentra.

La resolución de imports también funciona entre lenguajes: Rust use, Python import, TypeScript import/require, Go package, PHP use, todos mapeados a rutas de archivo reales.

Herramientas MCP: dando a la IA ojos en tu código

Aquí es donde Octocode cambia cómo trabajas con asistentes de IA.

Claude, Cursor y Windsurf todos soportan MCP. Cuando conectas Octocode como servidor MCP, tu asistente de IA obtiene tres herramientas:

Herramienta Qué hace
semantic_search Busca código, docs, texto o commits por significado
view_signatures Extrae estructura de archivos que coinciden con un patrón glob
graphrag Consulta el grafo de conocimiento por relaciones y dependencias

Configuración

Añade a tu config de Claude Desktop o Cursor:

{
	"mcpServers": {
		"octocode": {
			"command": "octocode",
			"args": ["mcp", "--path", "/your/project"]
		}
	}
}

Eso es todo. Ahora cuando le preguntas a Claude "¿cómo funciona el flujo de pago?", no alucina. Llama a semantic_search, lee el código real y te da una respuesta fundamentada en tu base de código.

Con integración LSP

octocode mcp --with-lsp "rust-analyzer"

Esto añade 6 herramientas más: goto_definition, hover, find_references, completion, document_symbols, workspace_symbols. Tu IA ahora puede moverse por el código como lo hace tu IDE, pero programáticamente.

Proxy multi-repo

¿Trabajas con múltiples repos? El proxy MCP auto-descubre repositorios git en un directorio y los sirve a través de un único endpoint HTTP:

octocode mcp-proxy --bind 127.0.0.1:8080 --path /workspace

Rendimiento

Los números importan más que las afirmaciones. Esto es lo que vemos en proyectos reales:

Métrica Pequeño (<1K archivos) Mediano (1-10K) Grande (10K+)
Velocidad de indexado 500+ archivos/seg 200-400/seg 100-200/seg
Latencia de búsqueda <50ms <100ms <200ms
Memoria 50-100MB 100-500MB 500MB-2GB
Almacenamiento (RaBitQ) ~300KB ~3MB ~30MB

La latencia de búsqueda es la que importa para MCP. Cuando Claude llama a semantic_search, no quieres esperar 5 segundos. Sub-100ms significa que la IA se siente instantánea.

El indexado es de una sola vez (más actualizaciones incrementales). Incluso un proyecto de 10K archivos se indexa en menos de un minuto.

14 lenguajes, una herramienta

Octocode usa Tree-sitter para parsear, lo que significa análisis AST real, no hacks de regex. Actualmente soportados:

Rust, Python, TypeScript, JavaScript, Go, PHP, C++, Ruby, Java, Bash, CSS/SCSS, Lua, Svelte, JSON, Markdown.

Cada lenguaje obtiene resolución de imports adecuada, extracción de símbolos y mapeo de relaciones. El parser de Go entiende los imports de paquetes. El parser de Rust sabe sobre use y mod. El parser de TypeScript maneja import y require. Esto no es talla única: cada parser de lenguaje está ajustado.

Qué cambió en la v0.13

Este es nuestro release más grande. 35 commits. Esto es lo nuevo:

  • Búsqueda de commits — busca el historial git por significado, con indexado de carga perezosa
  • Comandos CLI de IA — diff, explain, stats, review, commit, release
  • Enriquecimiento contextual de fragmentos — técnica de Recuperación Contextual de Anthropic
  • Cuantización RaBitQ — ~32x de compresión vectorial
  • Proveedores de embeddings OctoHub y Together AI
  • Indexado delta consciente de ramas — actualizaciones incrementales más inteligentes
  • Migrado al SDK rmcp — implementación oficial de MCP en Rust para estabilidad
  • GraphRAG mejorado — mejor resolución de nodos y búsqueda de caminos
  • 7 correcciones de bugs — commits raíz git, tipos de embedding, reranking, conteo de relaciones

Usamos Octocode para construir Octocode, así que cada borde áspero se atrapa rápido.

Empezando

macOS (Homebrew)

brew install muvon/tap/octocode

Script de instalación universal

curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh

Funciona en macOS (Intel + Apple Silicon), Linux (x86_64 + ARM64) y Windows.

Desde el código fuente

cargo install octocode

Primera ejecución

Configura un proveedor de embeddings (Voyage AI da 200M tokens gratis/mes):

export VOYAGE_API_KEY="your-key"

Indexa y busca:

cd your-project
octocode index
octocode search "how does authentication work"

Habilita GraphRAG:

octocode config --graphrag-enabled true
octocode index --force

Conéctalo a tu asistente de IA como servidor MCP, consulta la guía de integración MCP para configs de Claude, Cursor y Windsurf.

El punto real

Construimos Octocode porque grep no entiende el código. No porque haya algo malo con grep: hace exactamente lo que dice. Pero "encuentra la cadena auth" y "muéstrame cómo funciona la autenticación" son preguntas fundamentalmente diferentes.

El cambio de búsqueda por palabras clave a búsqueda semántica no es una función. Es un cambio de categoría. Y con MCP, ya no es solo para humanos: es también cómo los asistentes de IA entienden tu código.

Lo usamos para construir todo en Muvon. Es la herramienta que hace posible un equipo de dos personas. Y es gratis, código abierto, Apache 2.0.

260+ estrellas en GitHub. 14 lenguajes. Un binario de Rust. Pruébalo.