Octofs

Why Octofs?

Your AI coding assistant (Cursor, Claude, Windsurf, etc.) is smart — but it's blind to your filesystem. Octofs bridges that gap, giving your AI:

• Eyes — Read files, search content, explore directories
• Hands — Create, edit, batch-modify files atomically
• Context — Execute commands, manage working directories
• Reach — Transparent SSH/SFTP: every file tool accepts ssh:// URLs

┌─────────────────────────────────────────────────────────────┐│  You: "Refactor all error handling to use anyhow::Context" │├─────────────────────────────────────────────────────────────┤│  AI without Octofs:                                         ││  • "I can't see your project structure"                     ││  • "Please paste the relevant files"                        ││  • *Wastes 10 minutes on back-and-forth*                    │├─────────────────────────────────────────────────────────────┤│  AI with Octofs:                                            ││  • Reads your codebase directly                             ││  • Finds all error handling patterns                         ││  • Suggests atomic batch edits                              ││  • Applies changes with your approval                       │└─────────────────────────────────────────────────────────────┘

What Makes It Different

Installation

Cargo (crates.io)

cargo install octofs

Homebrew

brew install muvon/tap/octofs

npm (no Rust toolchain needed)

npx -y @muvon/octofs --version

The wrapper downloads the matching pre-built binary on first run. MCP config:

{  "mcpServers": {    "octofs": {      "command": "npx",      "args": ["-y", "@muvon/octofs", "mcp"]    }  }}

Pre-built Binaries

Download from GitHub Releases for your platform:

Each release also ships .mcpb bundles for one-click install in clients that support MCP bundles (e.g. Claude Desktop).

MCP Registry

Published to the MCP Registry as io.github.Muvon/octofs.

From Source

Requires Rust 1.95+.

git clone https://github.com/muvon/octofscd octofscargo build --release# Binary at ./target/release/octofs

Quick Start

Pair with Octocode

The shared-ID workflow requires the next Octocode release or a build of the updated source. OctoFS’s existing line-ID format is unchanged.

Use Octocode to find definitions, usages, and code relationships, then use OctoFS to read or edit the matching files. Octocode's MCP structural_search emits the same N:hh|content source line IDs that OctoFS accepts for batch_edit, using their shared Octolib utility. You do not need another view just to obtain IDs for lines already returned.

Run both servers against the same checkout. IDs describe that source snapshot: changed targets are verified at edit time, and an error supplies current context rather than guessing where to write. Exact-name lookups return complete small definitions; previews of larger matches name the ranges you can read with OctoFS.

1. Configure Your AI Assistant

The CLI uses a mcp subcommand — your config must pass ["mcp"] as args.

Claude Code (CLI):

claude mcp add octofs -- octofs mcp --path /path/to/your/projectclaude mcp add octocode -- octocode mcp --path /path/to/your/project

Codex CLI:

codex mcp add octofs -- octofs mcp --path /path/to/your/projectcodex mcp add octocode -- octocode mcp --path /path/to/your/projectcodex mcp list

The Octocode registration is optional. Install the servers you use and replace the paths with the same absolute checkout path. See the official Codex MCP documentation.

Cursor (~/.cursor/mcp.json):

{  "mcpServers": {    "octofs": {      "command": "octofs",      "args": ["mcp"]    }  }}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{  "mcpServers": {    "octofs": {      "command": "octofs",      "args": ["mcp"]    }  }}

Windsurf (~/.windsurf/mcp.json):

{  "mcpServers": {    "octofs": {      "command": "octofs",      "args": ["mcp"]    }  }}

If Octofs isn't on your PATH, use the full path to the binary (e.g. /usr/local/bin/octofs or ./target/release/octofs).

2. Restart Your AI Assistant

The MCP server starts automatically when your AI assistant connects.

3. Try It

Ask your AI assistant to:

• "Show me the project structure"
• "Read the main.rs file"
• "Search for all uses of unwrap() in the codebase"
• "Create a new file called test.rs"

Features

📁 Filesystem Operations

• View Files & Directories — Read a single file (call view in parallel for several), list directories with glob patterns, search content
• Smart Truncation — Large files are truncated intelligently to avoid overwhelming context windows
• Gitignore-Aware — Respects .gitignore patterns during directory traversal
• Line Ranges — Read specific line ranges with negative indexing (-1 = last line)
• Remote Files (SSH/SFTP) — Every file tool accepts ssh://user@host:port/path URLs (see Remote Filesystem)

✏️ Text Editing

• Create Files — Create new files with automatic parent directory creation
• String Replace — Replace exact string matches with fuzzy fallback for whitespace
• Delete — Remove a file (recoverable via undo)
• Undo — Revert last edit (up to 10 undo levels per file, in-memory)
• Batch Edit — Perform multiple insert/replace operations atomically on a single file
• Stale-Write Protection — Every edit target's N:hh id is verified against the file at apply time; a stale id fails with the current content and where it moved, instead of editing the wrong line

🔍 Code Intelligence

• Content Search — Search for strings within files with context lines
• Line Extraction — Copy specific line ranges from one file to another

🖥️ Shell & System

• Command Execution — Run shell commands with output capture
• Background Processes — Long commands automatically continue in background with completion notifications
• Working Directory — Set/get/reset working directory context for operations

Configuration

Line Identifiers

Every line is addressed by a composite id N:hh — its 1-indexed position plus a 2-character hex hash (FNV-1a) of its content. Octocode structural-search source output uses the same shared utility and IDs. view renders lines as N:hh|content:

1:a3|fn main() {2:f1|    println!("Hello");3:0e|}

Edit tools take these ids back as targets and verify the hash against the file before applying anything. A stale id (the file changed since it was viewed) fails with the current content around the target and where the expected content moved — so the model retargets from the error instead of re-reading the file. Edit results are diffs with fresh ids, so edits chain without re-viewing. Removed lines collapse to their old id range (-12:a3..15:f1 (4 lines)), and a trailing shift: lines after 40:b2 +3 line says how original line numbers below each edit moved, so ids the model still holds can be adjusted without a failed call.

This is the single line-id format — there is no mode switch. Plain line numbers are still accepted where a position alone is safe: view ranges (negative counts from the end) and the insert anchors 0 (file start) / -1 (append).

Shell Misuse Enforcement

Octofs detects shell misuse — commands like cat, grep, find, or sed that should use the dedicated MCP tools instead — and rejects them with an error explaining which tool to use. The call fails; nothing executes. This is intentional and not configurable: the dedicated tools give the model line ids, gitignore-awareness, and remote-host support that raw shell output cannot. Pipelines (cargo build 2>&1 | grep error) remain allowed — only standalone invocations of those programs are blocked.

Other guidance (out-of-bounds ranges, fuzzy-match notices) is appended to successful responses as ⚠️ hints without failing the call.

Transport Modes

STDIO (default)

Standard input/output transport. Works with all MCP clients.

octofs mcp

HTTP

Streamable HTTP transport for remote access or multi-client scenarios. Every tool, shell included, is reachable by whoever can connect, so access is gated:

# Loopback, no token: requests carrying a browser Origin header are rejectedoctofs mcp --bind 127.0.0.1:12345
# Any other address requires a bearer token; octofs refuses to start without oneOCTOFS_AUTH_TOKEN="$(openssl rand -hex 32)" octofs mcp --bind 0.0.0.0:12345

Connect clients to http://localhost:12345/mcp; with a token they send Authorization: Bearer <token>. The server speaks plain HTTP, so put it behind TLS or an SSH tunnel when the token crosses a network. --auth-token <TOKEN> works too, but command-line arguments are visible to other local users.

Working Directory

By default, Octofs operates in the current directory. Specify a different root:

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

Remote Filesystem (SSH/SFTP)

All path parameters — and --path itself — accept ssh:// or sftp:// URLs:

# Remote session root: relative paths resolve on the remote hostoctofs mcp --path ssh://[email protected]/var/www/app --ssh-key ~/.ssh/id_ed25519

view path="ssh://[email protected]/etc/nginx/nginx.conf"

• Login home — ssh://host (no path) and ssh://host/~/dir resolve against the login user's home, like ssh host / scp host:dir. ssh://host/dir stays absolute.
• OpenSSH config — host aliases are resolved through the local OpenSSH config (including Include and Match) and honor HostName, User, Port, and a single ProxyJump. Explicit URL values win, so both ssh://dev/path and ssh://[email protected]:2222/path work as expected. Multi-hop ProxyJump and ProxyCommand routing are rejected with a clear error.
• Authentication — uses the host's IdentityAgent (e.g. 1Password) or $SSH_AUTH_SOCK, then key files — --ssh-key if given, the host's IdentityFile entries, then the defaults in ~/.ssh (id_ed25519, id_ecdsa). Passphrase-protected key files are not supported directly; use an agent instead.
• RSA keys are not supported — the Rust rsa crate has an unfixed timing side-channel (Marvin attack, RUSTSEC-2023-0071), so octofs is built without RSA entirely. Use an ed25519 key instead (ssh-keygen -t ed25519); ecdsa also works. RSA-only setups fail with a clear error naming the key.
• Host keys — verified against ~/.ssh/known_hosts with the OpenSSH accept-new policy: unknown hosts are recorded on first use, a changed key fails closed.
• --ssh-timeout SECS — connection timeout (default 30). Connections are pooled per host, kept alive with transport keepalives, and reconnected automatically if they drop.
• shell stays local — commands always run on the machine where Octofs runs; only file tools (view, text_editor, batch_edit, extract_lines, workdir) reach remote hosts.

MCP Tools Reference

view — Read files, list directories, search content

File reading: (path is a single path; start/end are line numbers or line ids)

{"path": "src/main.rs"}                          // whole file{"path": "src/main.rs", "start": 10, "end": 20}  // lines 10–20{"path": "src/main.rs", "start": 42, "end": 42}  // single line{"path": "src/main.rs", "start": 80}             // line 80 → end of file{"path": "src/main.rs", "start": -20}            // last 20 lines{"path": "src/main.rs", "start": "12:a3", "end": "20:f1"}  // line ids from prior output

Output renders every line as N:hh|content — the N:hh prefix is the line id that batch_edit and extract_lines take as targets.

To read several files, make multiple view calls — they run in parallel.

Reuse content and line ids already returned. Read a complete relevant function or block in one call, combining adjacent windows. If its location is unknown, use content with enough context to understand the matches, then fetch only missing surrounding code. Do not re-read overlapping ranges or repeatedly narrow a range just to pick edit targets. Re-read when the file may have changed, output was truncated, or prior context is unavailable. Empty files return [empty file, 0 lines] on an initial or forced full read.

Images: a path with a png, jpg/jpeg, gif or webp extension returns the image itself as an MCP image block (up to 5 MB; the bytes must match the extension). start/end and content do not apply to it.

Delta views: a whole-file view of a file the session already served returns only the hunks changed since — the same .../-/+ style as edit results, with removed lines collapsed to their old id range — or [unchanged since you last viewed or edited it: N lines. Pass full: true to re-read.]. Octofs' own edits keep the cache current, so a re-view after your own batch_edit costs one line. Ranged views and content search always render exactly what was asked. full has no effect on ranges or searches; omit start/end and content search to force a complete file read. It does not change output limits.

{"path": "src/main.rs", "full": true}   // force the complete file (e.g. after context compaction)

Directory listing:

{"path": "src/"}{"path": "src/", "pattern": "*.rs"}{"path": "src/", "max_depth": 2, "include_hidden": true}

A bare listing of a remote directory (ssh://host/path, no pattern/content) defaults to max_depth: 1 — root entries only — because every subdirectory costs an SFTP round trip; pass max_depth explicitly to walk deeper. Searches with pattern or content always walk the whole tree, like rg.

pattern uses the same gitignore-style glob grammar as ripgrep's -g/--glob: without / it matches filenames at any depth, while a pattern containing / matches the returned relative path. It supports * within one path component, ** across directories, ?, character classes such as [abc], brace alternatives such as *.{rs,toml}, and leading ! exclusions. Use | to pass ordered globs in one MCP string; later globs take precedence:

{"path": ".", "pattern": "**/*.{rs,toml}|!target/**"}{"path": ".", "content": "unsafe", "pattern": "src/**/*.rs|!src/generated/**"}

The glob filters files discovered by Octofs' gitignore-aware traversal. Use include_hidden: true to include hidden paths; gitignored paths remain excluded. Patterns are limited to 4096 UTF-8 bytes, 64 |-separated rules, and 16 nested brace levels. They must be a single line and are validated before traversal. Escape a literal leading # or ! as \# or \!; otherwise # is rejected instead of silently acting as a gitignore comment. Empty brace alternatives such as {,rs} are rejected because ripgrep does not support them.

Content search: (literal by default; set regex: true for a Rust regex, (?i) = case-insensitive)

{"path": "src", "content": "fn main"}{"path": "src", "content": "unwrap()", "context": 3}{"path": "src", "content": "(?i)error", "regex": true}{"path": "docs|scripts|BENCHMARK.md", "content": "update_benchmark.py", "context": 4}

For an rg-style search across several roots, path accepts |-separated literal files and directories when content is set. The roots are not regexes: as with rg's positional path arguments, each one must exist. A real path containing | takes precedence over this shorthand. Root lists must be single-line, contain no duplicates, and are limited to 32 roots and 8192 UTF-8 bytes.

Directory listings annotate each file as path<TAB>NL<TAB>~Nt (line count + estimated tokens) so you can budget reads before opening files; binary files show path<TAB>(binary).

text_editor — Create, edit, replace text

Create file:

{"command": "create", "path": "src/new.rs", "content": "pub fn new() {}"}

Replace string: (old_text must match exactly once)

{  "command": "str_replace",  "path": "src/main.rs",  "old_text": "fn old()",  "new_text": "fn new()"}

Replace ALL occurrences (rename-style edits):

{  "command": "str_replace",  "path": "src/main.rs",  "old_text": "old_name",  "new_text": "new_name",  "replace_all": true}

Matching is progressive: exact → escaped-literal recovery (double-escaped \n/\t interpreted when the result matches uniquely) → whitespace-normalized fuzzy with indentation adjustment → rich diagnostics with the closest candidates and their line ids. CRLF files are matched in LF space and keep their line endings on write.

Delete file: (recoverable with undo_edit)

{"command": "delete", "path": "src/old.rs"}

Undo last edit:

{"command": "undo_edit", "path": "src/main.rs"}

Check after the edit: text_editor and batch_edit accept an optional check, a shell command (for example the test that covers the change) that runs after the edit is written and whose output follows the edit result. It needs the shell tool: a client that filters shell out of a session's tools sets experimental.session.shell to false in its client capabilities, and octofs then hides check from the edit tools and rejects it before writing anything. A missing field or any other value keeps check available.

batch_edit — Atomic multi-operation edits

Perform multiple insert/replace operations on a single file atomically.

Each operation has a start. For replace it's the first line of the range as a line id copied from view output (add end for a range; omit it for a single line). For insert it's the anchor to insert after — a line id, or the integers 0 (file start) / -1 (after last line). Every id is verified against the file before anything applies; a stale id fails with the current content so the model can retarget without a re-view. The result is a diff with fresh ids.

Insert at beginning:

{  "path": "src/main.rs",  "operations": [    {"operation": "insert", "start": 0, "content": "// Header\n"}  ]}

Replace lines:

{  "path": "src/main.rs",  "operations": [    {"operation": "replace", "start": "10:4b", "end": "15:c2", "content": "new code here"}  ]}

extract_lines — Copy lines between files

{  "from_path": "src/utils.rs",  "from_start": 10,  "from_end": 25,  "append_path": "src/new.rs",  "append_line": -1}

from_end is optional (omit to copy a single line). from_start and from_end each accept a line number or a line id ("12:a3", verified against the file). append_line positions the copy in the target: a line id to insert after (verified against the target), 0 = beginning, or -1 = end. Like every edit target it takes no other plain line number.

shell — Execute commands

Commands start in the foreground and return their output normally when they finish within about 10 seconds:

{"command": "cargo test"}{"command": "cd foo && cargo build"}

If a command is still running at that boundary, the same process continues in the background. The response returns its PID and linked output resource, and a completion notification arrives when it exits. There is no background flag and the command is never killed or restarted during the handoff. Multiple distinct commands may run concurrently, including from the same working directory. An exact duplicate command in the same working directory is rejected while the first copy is still running.

A client that declares the MCP tasks extension (io.modelcontextprotocol/tasks, SEP-2663) gets the promoted command as a task whose id is the job id. The client polls tasks/get and receives the same result a foreground call would have returned (an error result led by the exit code when the command failed); tasks/cancel stops the command's process group. While the command runs, the task's status message names its PID and kill command (kill -- -<pid>), the elapsed time, and its latest output line.

Other clients get the completion as resources/updated for the job resource (on a subscriptions/listen stream when the client opened one). Claude Code does not surface that to the model, so octofs also sends it as a Claude Code channel message (notifications/claude/channel) on pre-2026-07-28 connections — the exit code and output tail wake the session. Claude Code accepts channel messages only from servers enabled for the session, in interactive mode, and only on pre-2026-07-28 connections. Claude Code negotiates 2026-07-28 with stdio servers by default, so until it declares the tasks extension, opt out of that as well:

MCP_PROTOCOL_NEGOTIATION=legacy claude --dangerously-load-development-channels server:octofs

Without it, read the job's resource link when you need the result.

On Windows, shutdown cleanup terminates only direct child processes (no Unix process-group semantics); use taskkill /PID <pid> /T for process trees.

workdir — Manage working directory

Get current:

{}

Set new:

{"path": "/path/to/project"}

Reset to session root:

{"reset": true}

Architecture

octofs/├── src/│   ├── main.rs                  # Entry point, STDIO/HTTP server setup, signal handling│   ├── cli.rs                   # CLI argument parsing (clap): octofs mcp [OPTIONS]│   ├── mcp/│   │   ├── mod.rs               # McpToolCall, SessionRoot│   │   ├── server.rs            # OctofsServer (rmcp tool impl), Params structs, SessionWorkdir│   │   ├── request_ctx.rs       # Per-request hint queue + stale-file stamps│   │   └── fs/                  # Filesystem tool implementations│   │       ├── mod.rs           # Re-exports│   │       ├── core.rs          # view, text_editor, batch_edit, extract_lines│   │       ├── file_ops.rs      # view_file_spec, create_file_spec│   │       ├── text_editing.rs  # str_replace, batch_edit, undo, per-file locking│   │       ├── directory.rs     # Directory listing + content search│   │       ├── search.rs        # search_content│   │       ├── shell.rs         # Command execution, background, process cleanup│   │       ├── workdir.rs       # Working directory management│   │       ├── remote.rs        # SSH/SFTP path abstraction, SshHandler, SFTP pool│   │       └── fs_tests.rs      # Integration tests (cfg(test))│   └── utils/│       ├── mod.rs               # Module re-exports│       ├── line_hash.rs         # Composite line ids (N:hh), FNV-1a hashes, endpoint parsing│       └── truncation.rs        # Token estimation, smart truncation

Key design decisions:

• rmcp SDK — Official Rust MCP SDK (rmcp 3.x) for protocol handling
• Tokio — Async runtime; all file I/O uses tokio::fs, never blocking std::fs
• File locking — Per-file tokio::sync::Mutex prevents concurrent write conflicts
• Undo history — Up to 10 snapshots per file, in-memory (lost on restart)
• Path resolution — Relative paths resolve against the session workdir; no canonicalization (files may not exist yet)
• Stale-write detection — every edit target's N:hh id is verified against the file at apply time; a stale id fails with the current content instead of editing the wrong line

Development

# Buildcargo build --release
# Run testscargo test
# Lint (zero warnings policy)cargo clippy
# Formatcargo fmt
# Run locallycargo run -- mcp

Running Tests

# All testscargo test
# Specific testcargo test test_view_file
# With outputcargo test -- --nocapture

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick checklist:

1. Run cargo fmt before committing
2. Ensure cargo clippy passes with zero warnings
3. Add tests for new functionality
4. Update documentation as needed

Security

See SECURITY.md for security policy and reporting vulnerabilities.

License

Apache-2.0 — See LICENSE

Acknowledgments

• rmcp — Official Rust MCP SDK
• Model Context Protocol — The protocol specification