Octofs 0.16: un sistema de archivos de vanguardia para Claude Code y Codex

Leer un archivo de 400 líneas lleva microsegundos. Decidir volver a leerlo lleva un turno del modelo, y un turno del modelo lleva segundos. Esa asimetría explica toda la velocidad de un agente: el disco nunca es el cuello de botella. El cuello de botella es cuántas veces el modelo tiene que pararse, mirar y volver a preguntar antes de poder actuar.

Durante las últimas cuatro semanas usamos octofs como único sistema de archivos y único shell bajo Claude Code y Codex. Desactivamos las herramientas integradas de archivos y shell y arreglamos todo lo que estorbaba. Ocho versiones después, de la 0.15.0 a la 0.16.0, esto es lo que medimos: las mismas tareas terminan entre 2 y 2,5 veces más rápido, con aproximadamente el mismo número de tokens. El mismo modelo, más o menos los mismos tokens, menos tiempo.

Más rápido que las herramientas que traen los clientes, sin coste extra de tokens. Ese es el listón que nos pusimos para llamar a un sistema de archivos «de vanguardia», y la 0.16 lo supera. Este artículo reúne las notas de esas ocho versiones y la configuración exacta para que lo pruebes tú mismo.

Adónde se va el tiempo

Octofs no hace que el modelo piense más rápido. Elimina los turnos en los que el modelo solo estaba volviendo a comprobar lo que ya sabía. Cada uno de estos puntos forma parte del contrato de herramientas que ve el modelo:

  • Las ediciones devuelven lo que cambió, con ids nuevos. Cada línea que muestra octofs tiene un id: su número de línea más un hash corto de su contenido, con la forma N:hh|content. batch_edit y text_editor responden con un diff cuyas líneas llevan ids nuevos, así que la siguiente edición apunta directamente a ellas, sin releer entre medias. La 0.15.0 añadió al final una línea shift: que indica cuánto se desplazaron los números de línea por debajo de cada edición, de modo que los ids que el modelo conserva de una lectura anterior también siguen siendo válidos.
  • Releer devuelve solo la diferencia. Desde la 0.15.0, consultar un archivo completo que la sesión ya ha visto devuelve solo los fragmentos que cambiaron, o una marca de una sola línea que dice «sin cambios». Las propias ediciones de octofs mantienen esa caché al día, así que volver a comprobar tu propia edición cuesta una línea.
  • Un objetivo equivocado falla con la respuesta adjunta. Un id de línea obsoleto no se limita a fallar. El error trae el contenido actual y adónde se movió el objetivo, así que el reintento se hace sin otra lectura. Es así desde la 0.9.0.
  • Los comandos largos no retienen el turno. Un comando que sigue ejecutándose a los diez segundos se convierte en un trabajo en segundo plano. Es el mismo proceso: no se mata ni se reinicia, y el modelo recupera su turno. Esto llegó con la 0.13 y la 0.14.
  • Una respuesta, muchas llamadas. Las instrucciones del servidor le dicen al modelo sin rodeos que cada respuesta cuesta un viaje de ida y vuelta, así que debe pedir todas las llamadas independientes a la vez. La 0.16.0 afinó esa redacción.

No hemos desglosado el 2–2,5x por mecanismo, así que lee la lista como lo que es: el diseño, no el desglose de la mejora. Ninguna de estas ideas es nueva en esta versión. Lo que aportaron cuatro semanas bajo clientes reales es el pulido que mantiene al modelo en el camino rápido en lugar de dejar que se salga de él.

Qué cambió en la 0.15 y la 0.16

Claude Code vuelve a ver las herramientas

Esta es la corrección que conviene conocer si probaste octofs en un Claude Code reciente y no te cargó nada. La revisión de MCP de 2026-07-28 hace obligatorias las pistas de caché (ttlMs y cacheScope) en los resultados de list y read. El cliente estricto de Claude Code para esa revisión rechazaba los resultados que no las llevaban, así que no cargaba ninguna herramienta de octofs. La 0.16.0 emite esas pistas siempre que el cliente usa la revisión 2026-07-28 y deja intactas las conexiones más antiguas.

Trabajos en segundo plano que puedes leer con view

Un trabajo en segundo plano se expone como un enlace, octofs://jobs/<id>. Los modelos recurren primero a view sobre ese enlace, y Claude Code mantiene su lector genérico de recursos detrás de la búsqueda de herramientas (tool search), lo que cuesta un viaje de ida y vuelta extra. Por eso view sobre un enlace de trabajo devuelve el estado del trabajo y el final de su salida. Desde la 0.16.0 responde de inmediato en lugar de esperar a que el trabajo termine. Es el único cambio incompatible de este ciclo, y esta es la razón: un modelo puede consultar una compilación a mitad de ejecución y seguir trabajando.

Además, Claude Code no le muestra al modelo la notificación estándar resources/updated, así que el fin de un trabajo no despierta la sesión. El modelo recoge el resultado viendo el enlace cuando lo necesita, y por eso esa lectura nunca debe bloquear.

Una salvaguarda más en la 0.16.0: cuando un comando que guarda cambios temporalmente (git stash) pasa a segundo plano, la respuesta avisa al modelo de que al árbol de trabajo le faltan esos cambios hasta que el comando termine, para que mientras tanto no edite archivos ni dé la tarea por terminada.

Ediciones que dejan los archivos exactamente como estaban

  • Los finales de línea se conservan. Los archivos CRLF siguen en CRLF tras reemplazos e inserciones (0.15.5).
  • Las líneas en blanco finales se conservan, y una inserción vacía significa una línea en blanco en lugar de nada (0.16.0).
  • Las operaciones ambiguas se rechazan, no se adivinan. Una inserción dentro de un rango que el mismo lote reemplaza o elimina ahora falla con una explicación (0.15.0, 0.15.2).
  • Los diffs largos siguen siendo legibles. En el resultado de la edición, la parte central de un reemplazo exacto largo o de un bloque añadido largo se contrae en un rango de ids (0.16.0).

Un shell que mantiene al modelo en las herramientas dedicadas

Octofs rechaza los comandos de shell que duplican una herramienta dedicada, como cat, grep o ls, porque las herramientas dedicadas devuelven ids de línea y la salida en bruto del shell no. En este ciclo ese filtro se volvió preciso:

  • Las lecturas bloqueadas se detectan dondequiera que empiecen un comando: solas, encadenadas con && o ;, dentro de $(…) o al principio de un pipeline (0.16.0). Una etapa posterior del pipeline como cargo test 2>&1 | tail -20 sigue permitida.
  • sed y awk de solo lectura están permitidos (0.15.6). Volcar texto a stdout no es algo que cubra ninguna herramienta dedicada. sed -i sobre el propio archivo sigue rechazándose, con una indicación hacia las herramientas de edición.
  • Las redirecciones se analizan (0.16.0). Octofs rechaza escribir contenido de archivos en el proyecto con echo, printf o cat, porque el entrecomillado corrompe el contenido. Redirigir la salida de un programa, como cargo test > out.log, está permitido.
  • Cada rechazo nombra el programa bloqueado y dice que no se ejecutó nada, así que el modelo divide un comando compuesto en lugar de reintentarlo entero (0.15.6).

Hosts remotos y protocolo

  • ssh://host y ssh://host/~/dir se resuelven tomando como base el directorio personal del usuario que inicia sesión, igual que ssh host (0.15.0).
  • Se corrigió la búsqueda de contenido en árboles remotos, y un listado remoto sin más parámetros baja por defecto un solo nivel, porque cada subdirectorio cuesta un viaje de ida y vuelta por SFTP (0.15.1). La capa SFTP pasó a russh-sftp 3.0 (0.16.0).
  • Los esquemas de herramientas publicados ya no llevan ruido del generador como $schema, etiquetas format en los enteros y default: null (0.16.0). Las definiciones de herramientas se envían con cada petición, así que deben decir solo aquello sobre lo que el modelo actúa.

Haz el cambio: Claude Code

1. Instala octofs (Homebrew, Cargo o npm):

brew install muvon/tap/octofs
# or: cargo install octofs
# or: npm install -g @muvon/octofs

2. Regístralo para todos los proyectos:

claude mcp add --scope user octofs -- octofs mcp

Claude Code arranca el servidor en el directorio desde el que lanzaste claude, y ese directorio se convierte en la raíz del proyecto para octofs.

3. Desactiva los editores integrados en ~/.claude/settings.json:

{
	"permissions": {
		"allow": ["mcp__octofs"],
		"deny": ["Edit", "Write", "NotebookEdit"]
	}
}

Esta es la configuración detrás de nuestras cifras. Un nombre de herramienta sin más en deny elimina la herramienta del contexto del modelo por completo, y mcp__octofs permite todas las herramientas de octofs sin pedir confirmación. Bash y Read se quedan: en nuestras ejecuciones el modelo envió igualmente sus lecturas, ediciones y comandos a través de octofs, y Read es como Claude Code mira imágenes y PDF. Denegar también Bash sale mal, porque devuelve al conjunto de herramientas del modelo las herramientas independientes Glob y Grep de Claude Code.

Haz el cambio: Codex

1. Añade octofs y desactiva el shell integrado en ~/.codex/config.toml:

[features]
shell_tool = false
unified_exec = false

[mcp_servers.octofs]
command = "octofs"
args = ["mcp"]
default_tools_approval_mode = "approve"

Pega el bloque tal cual y no ejecutes además codex mcp add octofs: escribe la misma tabla [mcp_servers.octofs], y Codex se niega a arrancar con una tabla definida dos veces. shell_tool y unified_exec son los dos ejecutores de comandos de Codex. Con ambos desactivados, todo comando pasa por el shell de octofs, paso a segundo plano incluido, y default_tools_approval_mode permite que las herramientas de octofs se ejecuten sin pedir aprobación.

2. Dirige las ediciones a octofs. Codex no tiene ningún interruptor para desactivar su editor integrado apply_patch (openai/codex#8161 se cerró como «no planificado»), así que díselo al modelo en AGENTS.md:

## Tools

- Use octofs for all file and shell work: `view` to read, list and search; `batch_edit` or `text_editor` to edit; `shell` for builds, tests and git. Never use apply_patch.
- Put every call that doesn't depend on another call's result in one response.
- A command still running after ~10s becomes a background job. Don't wait for it: take the next step, and `view` its `octofs://jobs/<id>` link when you need the result.

El mismo bloque funciona en CLAUDE.md, aunque en nuestras ejecuciones Claude Code eligió octofs sin él.

Pruébalo

La forma más rápida de comprobar nuestra cifra es repetir algo que ya hayas hecho. Elige una tarea reciente, como la corrección de un bug o una refactorización que toque unos cuantos archivos. Ejecútala una vez con las herramientas integradas y otra con octofs, con el mismo modelo y el mismo prompt, y compara el tiempo real y los tokens. Espera que los tokens se queden más o menos igual. La diferencia se nota en el tiempo.

¿Ya usas octofs? Actualiza con brew upgrade muvon/tap/octofs, cargo install octofs o npm install -g @muvon/octofs, o descarga un binario precompilado para Linux, macOS o Windows (x86_64 y ARM64) desde la página de versiones. Un apunte sobre el comportamiento: view sobre un enlace de trabajo en segundo plano ya no se bloquea hasta que el trabajo termina. Si algo que construiste dependía de eso, vuelve a leer el enlace cuando el trabajo termine.

Octofs es código abierto (Apache 2.0) en github.com/Muvon/octofs. Presentamos Octofs explicó por qué construimos nuestro propio servidor de sistema de archivos, la 0.9.0, por qué no se puede confiar en un número de línea, y la 0.14, por qué tampoco se puede confiar en una llamada a herramienta bloqueada. Este artículo es el resultado de los tres: un agente que deja de volver a comprobar lo que ya sabe termina el mismo trabajo entre dos y dos veces y media más rápido.