Octofs
Hash-Verified Edits • SSH/SFTP Everywhere • Auto-Background Shell
The filesystem engine every Octomind agent runs on — and a standalone MCP server anyone can point at Cursor, Claude, or Windsurf. Hash-verified line edits so a stale view can never silently corrupt a file, transparent SSH/SFTP on every tool, and a shell that knows the difference between a real command and a call that should have used the dedicated tool. Native Rust, zero runtime.
brew install muvon/tap/octofsKey Features
Octomind's Own Filesystem Engine
Every developer agent Octomind ships — 150+ specialists in the tap registry — reads, edits, and runs shell through this exact server. It's delivered as a companion stdio process via the built-in tap's filesystem-read and filesystem-write capabilities, not a hardcoded server block: the same six tools (view, text_editor, batch_edit, extract_lines, shell, workdir), the same binary you can also run standalone in Cursor, Claude Desktop, or Windsurf.
Hash-Verified, Fuzzy-Fallback Editing
Every line carries a composite id — position plus a content hash — so `batch_edit` and `text_editor` verify the target against the live file before touching it; a stale id fails closed with the current content and where it moved. `str_replace` itself falls back progressively: exact match, then escaped-literal recovery, then whitespace-normalized fuzzy matching with indentation adjustment, then rich diagnostics naming the closest candidates. CRLF files match in LF space and keep their original line endings on write. Edit results return as diffs with fresh ids, so edits chain without a re-view.
Transparent SSH/SFTP
Every file tool — view, edit, batch_edit, extract_lines, workdir — accepts ssh:// and sftp:// URLs, no separate remote workflow. Full OpenSSH config resolution (Include, Match, ProxyJump), agent auth first, known_hosts pinned on accept-new. RSA is built out entirely — the Rust rsa crate has an unfixed timing side-channel (Marvin attack) — so only ed25519 and ecdsa keys work.
Shell Misuse Enforcement
Standalone cat, grep, find, or sed calls through the shell tool are rejected outright, with the dedicated tool named in the error — nothing executes. Pipelines like cargo build 2>&1 | grep error stay allowed. It's not configurable: the dedicated tools give the model line ids, gitignore-awareness, and remote-host support raw shell output can't.
Automatic Background Handoff
Commands run in the foreground and return output normally if they finish in about 10 seconds. Past that, the same process keeps running in the background automatically — no flag to set — and a completion notification carries the PID and full output back when it exits.
Token-Budgeted Intelligence
Directory listings annotate every file with line count and estimated tokens before you open anything. Gitignore-aware traversal, ripgrep-grammar globs (**/*.{rs,toml}|!target/**), and multi-root content search across up to 32 literal paths in one call.
Why Octofs?
AI edits the wrong line because the file changed since it last looked at it.
Every edit target is a hash-verified N:hh line id, checked against the file at apply time. A stale id fails with the current content and where it moved — the model retargets from the error instead of silently corrupting the file.
Your project partly lives on a remote box, and every other 'AI filesystem' tool only sees localhost.
Every file tool accepts ssh:// and sftp:// URLs — OpenSSH config resolution, agent auth, known_hosts pinning, RSA disabled by design. Same tools, remote or local, no separate integration to configure.
A model calls cat, grep, or sed through the shell tool and gets raw output with no line ids, no gitignore-awareness, no structure.
Octofs rejects standalone shell calls to those programs and names the dedicated tool to use instead. The call fails; nothing executes. Pipelines stay allowed — only the direct misuse is blocked.
A long build or test run blocks the session, or gets backgrounded and its output lost.
Commands run foreground-first for about 10 seconds, then continue in the background automatically. The response carries the PID and a completion notification arrives with the full output — nothing to configure, nothing lost.
MCP Tools
Available via Model Context Protocol for AI assistants
view Read files (parallel-safe), list directories with glob patterns, search content — local or over ssh://text_editor Create, str_replace (progressive fuzzy match), delete, and undo_edit — up to 10 levelsbatch_edit Atomic multi-operation insert/replace on one file, every target hash-verifiedextract_lines Copy a line range from one file into another by line idshell Run commands with automatic foreground-to-background handoff and misuse rejectionworkdir Get, set, or reset the session working directory — local or remoteWhen to Use Octofs
Edit a Remote Box Like It Was Local
Point --path at ssh://deploy@host/var/www/app and every file tool works against the remote host directly — same line ids, same safety, same tools. No scp round-trip, no separate remote workflow.
Unattended Editing That Cannot Silently Corrupt
A model that viewed a file five turns ago can't blind-write over changes that happened since — the hash-verified line id fails closed and hands back where the content actually moved.
Long Builds Without Blocking the Session
Kick off a test suite or build through shell — if it's still running past ~10 seconds, it keeps going in the background on its own and reports back on completion. No flag, no lost output.
Multi-Root Code Search
Search literal or regex content across several directories or files in one call — `docs|scripts|BENCHMARK.md` — with gitignore respected and per-file token budgets shown before you open anything.
Works With
Install
Homebrew
brew install muvon/tap/octofs One command. Auto-updates. No build step.
Build from Source
git clone https://github.com/muvon/octofs && cd octofs && cargo build --releaseTech Stack
Built in the Open
Octofs is open source under the Apache 2.0 license. Contributions, issues, and stars are welcome.