Octofs: The File Server That Stops Your AI from Breaking Your Code

Your AI assistant just edited three files. Two are fine. The third has a function duplicated, a closing brace missing, and the indentation is completely wrong. It looked confident. It wasn't.

This happens more than anyone wants to admit. AI agents are powerful code editors — until they hallucinate a line number, misremember indentation, or include surrounding context in a replacement that shouldn't be there. The edit succeeds technically. The file is now broken. You didn't notice until the build failed.

Octofs is an MCP filesystem server built to prevent exactly this. It gives your AI agent eyes, hands, and a safety net — the ability to read, edit, create, and search files, with multiple layers of protection against the mistakes that AI models make when they touch code.

Today we're introducing Octofs 0.4.0 — the current state of a project that started as a simple file server and evolved into something we think every AI agent needs.

Why we built a filesystem server in the first place

We didn't start here. We started with Octomind — a runtime for specialist AI agents. You run octomind run developer:general and get a fully-tooled senior developer in five seconds. The agent needs to read code, edit files, run commands, search your project. It needs filesystem access.

The MCP ecosystem already had a reference filesystem server. So we tried it. It worked — until it didn't. The AI would reference line numbers that shifted after a previous edit. It would pass slightly wrong whitespace to a string replace and get a silent mismatch. It would duplicate lines at the edges of a replacement range. It would try to run grep through shell when a dedicated search tool existed.

Each failure was small. Each one required human intervention. At agent scale — running hundreds of edits across dozens of files — the small failures compound into something that stops being useful.

So we wrote our own. Not because filesystem access is interesting. Because the failure modes of AI-driven file editing are predictable, and a good server can catch most of them before they become your problem.

The AI hallucination problem in file editing

Here's what actually breaks:

Wrong line numbers. The agent reads a file, plans five edits, executes them sequentially. Edit one adds three lines. Now every subsequent line reference is off by three. The agent doesn't notice because it's working from the original mental model.

Indentation hallucination. The agent knows the code it wants to write. It gets the indentation slightly wrong — two spaces instead of four, or tabs when the file uses spaces. The exact match fails. The edit silently does nothing, or worse, the agent retries with an even more confused version.

Context duplication. The agent includes one extra line of surrounding context in its replacement text. Now that line appears twice in the file. If it's a closing brace, the code might still parse. If it's a meaningful line, you have a subtle bug.

Ambiguous matches. The agent passes a three-line string that appears in four places in the file. Which one should be replaced? Without disambiguation, the edit either fails or hits the wrong location.

These aren't edge cases. They're the default experience of running AI agents at scale. And they're all solvable — not by making the AI smarter, but by making the file server smarter about the mistakes it knows the AI will make.

How Octofs catches the mistakes

Three-stage progressive matching

When the AI calls str_replace with an old_text that should match something in the file, Octofs doesn't just try once and fail. It runs three stages:

Stage 1: Exact match. The old_text string matches exactly once in the file. Replace it. Done. This is the happy path — it handles most edits correctly.

Stage 2: Whitespace-normalized fuzzy match. The exact match fails, so Octofs normalizes whitespace across both the provided text and the file content — collapsing runs of spaces, trimming lines — and tries again. If there's exactly one normalized match, it auto-adjusts the indentation of the replacement text to match the actual file, applies the edit, and tells the AI what happened via a hint. The AI learns. The edit succeeds.

Stage 3: Rich diagnostics. Neither exact nor fuzzy match works. Instead of a generic "no match found" error, Octofs runs a sliding-window similarity search across the entire file, finds the three closest matches, and returns them with similarity percentages, line numbers, a diagnosis of why they differ (indentation mismatch, whitespace only, or content differs), and a preview of the candidate text. The AI can then use batch_edit with the exact line range — or fix its old_text and try again.

It's what happens every time an edit fails, and it's the single biggest reduction in failed-edit retries we've seen.

Hash-based line identification

Line numbers are a terrible identifier for AI-driven edits. They shift. The AI reads a 500-line file, plans to edit lines 142-156, but a previous edit inserted four lines at line 80. Now the target is at 146-160. The AI doesn't know this unless it re-reads the file — which it might not do.

Octofs offers an alternative: hash-based line identifiers. Each line gets a 4-character hex hash derived from its position and content. Unlike line numbers, hashes are stable across edits — a line's hash doesn't change just because another line was inserted above it. The AI can reference lines by hash, and even after multiple edits, those references stay valid.

The hash algorithm uses FNV-1a folded to 16 bits, keyed on "<position>:<content>". Position is included specifically to handle duplicate lines — two identical lines at different positions always get different hashes, with no collision resolution needed.

Enable it with --line-mode hash and every tool response returns hashes instead of numbers. The AI uses them for batch_edit ranges, view ranges, and diagnostics. Line-number drift stops being a problem.

Duplicate detection at replacement boundaries

Here's a subtle one. The AI plans a replacement for lines 100-105. It includes line 99 (the line before the range) in its replacement content — not because it wants to change it, but because it's "providing context." Now line 99 appears twice. If it's a closing brace or an empty line, maybe no harm. If it's actual code, you have a bug.

Octofs checks every replacement for boundary duplication. It compares the first line of the replacement against the line immediately before the target range, and the last line against the line after. If either matches, it rejects the edit with a specific message: "Duplicate line detected in operation 2: content's first line matches line 99 (just before the replacement range [100-105]). Do NOT include surrounding unchanged lines."

Structural noise — lone closing braces, empty lines — is exempt from this check. They legitimately appear at boundaries. Compound closers like }); are not exempt. They carry real semantic meaning.

Conflict detection for batch operations

batch_edit lets the AI perform multiple insert and replace operations on a single file atomically. But what if two replacements overlap? What if two inserts target the same anchor line?

Octofs validates every operation against every other operation before touching the file. Replace-vs-replace ranges that overlap are rejected. Insert-vs-insert at the same anchor are rejected (ambiguous ordering). Insert-vs-replace never conflicts — they operate on conceptually different positions (the gap after a line vs. the line's content).

If there's a conflict, the error message includes the operation indices and the specific line ranges involved. The AI can fix its plan and retry. No partial corruption.

Atomic writes with undo history

Every edit goes through atomic_write: write to a temp file in the same directory, then rename over the target. The file is never in a partial state. If the process crashes mid-write, the original stays intact. The rename is the only destructive step, and it's atomic at the filesystem level.

Before every write, Octofs saves the previous version. Up to ten undo levels per file. If an edit goes wrong, the AI can call undo_edit and the file reverts. No manual git restore. No "oops, I need to fix what the AI just did."

Shell misuse detection

The AI has shell access. That's necessary — it needs to run builds, tests, linters. But it also sometimes tries to use cat to read a file, or grep to search for text, or sed to edit a line. These all have dedicated, better tools in Octofs.

When the AI runs a shell command that matches a known misuse pattern, Octofs detects it and injects a hint into the next tool response: "Prefer view for reading files (line-numbered, supports ranges)." The AI sees the hint, adjusts its behavior, and uses the right tool next time.

Non-interactive shell enforcement

Shell commands run with stdin=null, a dedicated process group, and environment variables like GIT_TERMINAL_PROMPT=0 and PAGER=cat. The AI can't accidentally spawn an interactive prompt that hangs the session. Git won't ask for credentials. sudo won't ask for a password. less won't invoke. The command either succeeds or fails — no third state.

On shutdown, every in-flight shell child's process group is killed with SIGKILL. No orphan processes. No zombie shells eating memory.

The current state: 0.4.0

Octofs 0.4.0 isn't a release announcement — it's where the project is right now, and it's stable enough to rely on. Here's what the current version delivers:

Multi-range file views. Read non-contiguous sections of a file in a single call — [[1, 50], [200, 250], [400, 430]] — instead of three separate requests. Fewer round trips. Less context waste.

Structured line range types. Line ranges are now first-class types with proper validation — not raw JSON arrays that the AI has to format correctly. The server validates shape, bounds, and count before doing anything.

Non-interactive shell enforcement. Shell commands are guaranteed non-interactive. No more hanging prompts, no more credential dialogs, no more pager-invoked garbage output.

Out-of-bounds clamping. Line ranges that exceed the file length are clamped, not rejected. The AI asks for lines 1-1000 in a 200-line file? It gets lines 1-200. No error. No retry.

Per-file line ranges in multi-file views. When viewing multiple files at once, each file can have its own line range. paths: ["a.rs", "b.rs", "c.rs"] with lines: [[1,50], null, [10,30]] — first file shows 1-50, second shows everything, third shows 10-30.

Canonicalized file locking. File locks use canonicalized paths, so ./src/main.rs, src/main.rs, and /absolute/path/to/src/main.rs all resolve to the same lock. No concurrent-write corruption from path aliasing.

Pure-Rust search. Content search doesn't shell out to ripgrep anymore. It's a pure-Rust implementation that's fast enough, has zero external dependencies, and works identically on every platform.

The tools

Octofs exposes seven MCP tools:

Tool	What it does
view	Read files, list directories, search content. Supports multi-file, multi-range, hash-based line IDs, content search with context lines
text_editor	Create files, replace text with progressive matching, undo edits
batch_edit	Multiple atomic insert/replace operations on a single file, with conflict detection
extract_lines	Copy line ranges from one file to another
shell	Execute commands with background support, misuse detection, non-interactive enforcement
workdir	Manage working directory context

All tools support both STDIO and Streamable HTTP transport. All tools are gitignore-aware during directory traversal. All tools respond with line-numbered (or hash-identified) output so the AI has stable references for subsequent operations.

How it fits: Octomind + Octofs

Octofs works with any MCP-compatible client — Claude Desktop, Cursor, Windsurf, Zed. But it's designed for Octomind.

Octomind's agents read your codebase, plan changes, and execute edits through Octofs. Octobrain — our memory server — stores what the agent learns during the session. Octolib handles every LLM call. Together they're a complete stack for AI-driven development:

• Octolib talks to AI models
• Octobrain remembers across sessions
• Octofs safely touches your files
• Octomind orchestrates everything

Each piece is open source. Each piece works standalone. Together they solve the problem of giving an AI agent reliable, safe access to a codebase.

Open source, Rust-native

Octofs is on GitHub under Apache-2.0. It's built in Rust — not because we fetishize performance, but because file operations benefit from compile-time correctness, zero-cost async, and no garbage collection pauses. The binary is small, fast, and has zero runtime dependencies beyond the OS.

# Build from source (requires Rust 1.95+)
git clone https://github.com/muvon/octofs
cd octofs && cargo build --release

# Or download a pre-built binary from GitHub Releases

Add to your Claude Desktop config:

{
  "mcpServers": {
    "octofs": {
      "command": "/path/to/octofs",
      "args": ["--line-mode", "hash"]
    }
  }
}

Use hash mode for any agent that does multi-step edits. The stable line references eliminate an entire class of failures.

What's next

We're working on smarter diagnostics — when an edit fails, Octofs shouldn't just tell the AI what went wrong. It should suggest the fix. We're also exploring pattern-based edit validation: if the AI is editing a Rust function, Octofs could check that the result still parses as valid Rust before writing it.

The file server isn't the exciting part of an AI agent stack. It's the part that has to work perfectly, every time, or everything else falls apart. That's the requirement Octofs is built around — and it's open source on GitHub under Apache-2.0 if you want to dig in.