0.15.0 hizo que Octocode fuera local por defecto: sin necesidad de API key, con los embeddings ejecutándose en tu propia máquina mediante fastembed. Clonas un repositorio, ejecutas octocode index, obtienes resultados, nada sale de tu portátil.

fastembed ejecuta el puñado de modelos que incluye, en tu CPU, dentro del proceso. Genial para empezar — menos genial cuando quieres un modelo de embedding más grande o más nuevo, una GPU, o un único servidor que comparta todo el equipo. El proveedor local se añadió exactamente para eso: apunta Octocode a cualquier servidor de embeddings compatible con OpenAI — Ollama, LM Studio, vLLM, llama.cpp, LocalAI, text-embeddings-inference — e indexa con el modelo que aloje.

0.17.1 es la versión donde eso funciona de principio a fin. El proveedor ahora detecta automáticamente la dimensión de embedding de tu modelo, que es la pieza que la indexación necesita para construir su almacén de vectores. Elige el modelo, elige el hardware, y tu código sigue sin salir nunca de tu red.

Este post cubre el proveedor local más los otros cambios desde 0.16.0 (el resumen de junio te puso al día hasta ahí): el modo MCP de solo lectura y la búsqueda estructural con precisión AST de 0.16.1.

Trae tu Propio Servidor de Embeddings

Dos líneas de configuración:

[embedding]
code_model = "local:nomic-embed-text"
text_model = "local:nomic-embed-text"

El prefijo local: le indica a Octocode que envíe las peticiones de embedding a un servidor que hable la API /v1/embeddings de OpenAI. Por defecto apunta a http://localhost:11434/v1/embeddings — el puerto de Ollama — así que si Ollama ya está en ejecución, no hay nada más que configurar:

ollama pull nomic-embed-text
octocode index

Apuntar a otro sitio es una única variable de entorno:

# vLLM, LM Studio, servidor llama.cpp, LocalAI, text-embeddings-inference —
# cualquier cosa que exponga POST /v1/embeddings
export LOCAL_EMBED_API_URL="http://gpu-box.internal:8000/v1/embeddings"

# Opcional — se envía como `Authorization: Bearer <key>` si tu servidor lo requiere
export LOCAL_EMBED_API_KEY="..."

Esa es toda la configuración. Sin SDK, sin pegamento específico de cada proveedor.

Sin dimensión que configurar

Distintos modelos de embedding producen vectores de distinta anchura — 384, 768, 1024 — y el almacén de vectores tiene que conocer esa anchura de antemano para construir su índice. Un servidor compatible con OpenAI no la anuncia en ninguna parte, así que Octocode la averigua por ti: la primera vez que construye un proveedor para tu modelo, envía una pequeña petición de sondeo, lee la anchura del vector directamente de la respuesta, y la cachea durante el resto de la ejecución. El índice se construye entonces en torno a esa dimensión.

El resultado práctico: cualquier modelo que tu servidor pueda servir simplemente funciona. No hay nada que consultar o configurar por modelo. Cambia nomic-embed-text por un modelo de código más grande y Octocode se adapta a la nueva anchura en la siguiente indexación — el único requisito es reindexar, ya que los vectores de distintos modelos no son comparables.

fastembed vs. local — ¿cuál?

Ambos son locales. La diferencia es quién ejecuta el modelo.

fastembed: local:
Ejecución Dentro del proceso (ONNX, en tu CPU) Un servidor separado que tú gestionas
Modelos El conjunto curado que incluye Octocode Lo que tu servidor pueda alojar
Hardware La CPU de esta máquina Donde viva el servidor — GPU, una máquina compartida
Configuración Cero — los modelos se descargan en el primer uso Tú ejecutas Ollama/vLLM/etc.

Recurre a fastembed cuando quieras cero configuración y un buen valor por defecto. Recurre a local cuando se te haya quedado pequeño:

  • Un modelo que fastembed no incluye — un modelo de embedding de código más nuevo, uno más grande, algo afinado para tu dominio. Si tu servidor puede servirlo, Octocode puede indexar con él.
  • Hardware de verdad. Generar embeddings de un monorepo grande en la CPU de un portátil es lento. Apunta LOCAL_EMBED_API_URL a un servidor con GPU y el embedding se ejecuta allí en lugar de en tu portátil.
  • Un servidor para todo el equipo. Ejecuta una única instancia de Ollama o vLLM; el Octocode de cada desarrollador apunta a ella. Vectores consistentes, un único lugar donde actualizar el modelo.

Y la propiedad que no cambia entre ambos: es búsqueda de código privada y autoalojada — tu código permanece dentro de tu red. La misma garantía que entregó 0.15.0, ahora sin estar encajonado en los modelos incluidos o en la CPU de tu portátil.

Modo MCP de Solo Lectura

Por defecto, cuando un agente de IA se conecta al servidor MCP de Octocode, el servidor ahora sirve búsquedas sobre tu índice existente y nunca lo toca. Sin indexador en segundo plano, sin file watcher, sin reindexación sorpresa lanzada en el momento en que tu asistente se conecta.

Esto es el interruptor mcp_index, y false es el valor por defecto:

[index]
# false (default): MCP serves search, view_signatures, and structural_search
#   over the EXISTING index, read-only. No background indexing or file watcher.
# true: MCP keeps the index fresh in-process with a background indexer + watcher.
mcp_index = false

¿Por qué solo lectura por defecto? Indexar y servir son trabajos distintos. Indexas en CI, en un hook de git, o a mano — deliberadamente, cuando el código cambia. El trabajo del servidor MCP es responder a las preguntas del agente de forma rápida y predecible, no levantar un file watcher y volver a generar embeddings de tu repositorio porque un editor tocó un archivo. Solo lectura significa menor uso de recursos en reposo, sin contención, y sin trabajo inesperado en el momento en que una herramienta se conecta.

El comando index de la CLI no se ve afectado — octocode index indexa, igual que siempre. mcp_index solo controla el indexador dentro del proceso que el servidor MCP ejecutaría de lo contrario.

Hay también un pequeño detalle para el modo de solo lectura: si una búsqueda semántica vuelve vacía (porque el índice está desactualizado o aún no se ha construido), Octocode añade una sugerencia de una línea que orienta al agente hacia structural_search y view_signatures en lugar de dejarlo reintentar la búsqueda semántica en el vacío.

¿Quieres el viejo comportamiento siempre-fresco — un servidor de larga duración que se mantiene actualizado solo? Pon mcp_index = true y el indexador en segundo plano y el watcher vuelven.

Búsqueda Estructural, Ahora con Precisión AST (0.16.1)

0.16.1 no tuvo su propio post, así que merece la pena destacarlo: el servidor MCP de Octocode ganó una herramienta de búsqueda estructural propiamente dicha, separada de la búsqueda semántica y del grep.

La búsqueda semántica es genial para "¿dónde vive el reintento de pago?" El grep es genial para cadenas literales. La búsqueda estructural es para las preguntas intermedias — encuentra esta forma de código, independientemente del formato o el nombrado — y para símbolos:

  • Definiciones y referencias de símbolos con soporte de comodines — "¿dónde se define handle_* y quién lo llama?"
  • Estrategias de coincidencia inteligente y flexible. Como las mejoras del grep estructural en 0.15.0, se recupera cuando el tipo de nodo solicitado es incorrecto para el lenguaje en lugar de no devolver nada.
  • Restricciones de metavariables — acota las coincidencias con regex y filtros relacionales, no solo con patrones en bruto.
  • Seguimiento de breadcrumbs para que cada coincidencia te diga en qué clase/función/módulo está anidada, entre lenguajes (incluido Swift).
  • Paginación y caché de peticiones para que un agente pueda recorrer grandes conjuntos de resultados sin volver a ejecutar el escaneo completo.

Por debajo recorre el árbol respetando gitignore y en paralelo, con prefiltrado por tokens literales y un fallback léxico cuando el camino del AST vuelve vacío — rápido en repositorios grandes, y sin perder coincidencias en silencio. Para un agente de IA, eso es una forma precisa y navegable de encontrar estructuras de código exactas y rastrear símbolos.

Todo lo Demás

view_signatures acepta un único archivo como string. Los agentes (y los humanos) pueden pasar un archivo como un string simple en lugar de envolverlo en un array de un solo elemento. Menos fricción para el caso más común.

Las definiciones de herramientas ya no están hardcodeadas. La lista de herramientas del servidor MCP se genera en lugar de mantenerse a mano, lo que evita que el esquema y la implementación se desincronicen.

Limpieza de dependencias y CI. Dependencias de Rust actualizadas, el pipeline de release migrado a workflows reutilizables compartidos. Sin cambios de comportamiento — solo un build más ordenado y fiable.

Actualización

# Homebrew
brew upgrade muvon/tap/octocode

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

# Cargo
cargo install octocode --version 0.17.1

Si estás contento con fastembed, no hay nada que hacer — tu configuración y tu índice siguen funcionando. Para cambiar a tu propio servidor de embeddings:

  1. Arranca un servidor que hable la API de embeddings de OpenAI (p. ej. ollama serve) y carga un modelo.
  2. Pon code_model / text_model en local:<model> en config.toml. Apunta LOCAL_EMBED_API_URL al servidor si no está en el puerto por defecto de Ollama.
  3. Reindexa — los vectores cambian con el modelo: octocode clear && octocode index.

¿Quieres que tu servidor MCP siga indexando en segundo plano como en las versiones anteriores? Pon mcp_index = true. De lo contrario, el valor por defecto de solo lectura toma el control — indexa desde la CLI o CI, y deja que el servidor sirva.

Octocode es open source (Apache 2.0) en github.com/Muvon/octocode. Es el motor de búsqueda de código detrás de Octomind — y ahora puedes ejecutar cada embedding que genera en hardware que tú controlas, con el modelo que elijas.