---

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

Feature	Octofs	Typical Alternatives
Implementation	Compiled Rust binary, no runtime	Python/Node script
Content Search	Built-in search with context lines	String matching only
Batch Operations	Atomic multi-edit on single file	One-at-a-time
Line Modes	Hash-based (stable across edits) or number-based	Number-only
Transport	STDIO + Streamable HTTP	STDIO only
Shell Integration	Foreground + background process support	Limited or none
Remote Files	Transparent SSH/SFTP on every file tool	None
Safety	Gitignore-aware, stale-write detection, path validation	Full filesystem access

---

Installation

Cargo (crates.io)

cargo install octofs

Homebrew

brew install muvon/tap/octofs

Pre-built Binaries

Download from GitHub Releases for your platform:

Platform	Target
Linux (x86_64)	x86_64-unknown-linux-musl
Linux (ARM64)	aarch64-unknown-linux-musl
Windows (x86_64)	x86_64-pc-windows-msvc
Windows (ARM64)	aarch64-pc-windows-msvc
macOS (Intel)	x86_64-apple-darwin
macOS (Apple Silicon)	aarch64-apple-darwin

MCP Registry

One-click install via the MCP Registry entry io.github.Muvon/octofs.

From Source

Requires Rust 1.95+.

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

---

Quick Start

1. Configure Your AI Assistant

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

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 — Edits fail fast if the file changed on disk since it was last viewed (external-edit detection, like an IDE's "file changed on disk" guard)

🔍 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 — Run long commands in background, get PID for later management
• Working Directory — Set/get/reset working directory context for operations

---

Configuration

Line Identifier Modes

Octofs supports two modes for identifying lines in files, set once at startup:

Number Mode (default)

Lines are identified by 1-indexed line numbers:

1: fn main() {
2:     println!("Hello");
3: }

Use for: Simple operations, one-off edits.

Hash Mode

Lines are identified by 4-character hex hashes (FNV-1a, position-dependent — same content at different lines produces different hashes):

a3bd: fn main() {
c7f2:     println!("Hello");
e9f1: }

Use for: Complex multi-step edits where line numbers would shift. Hashes stay stable across edits.

Enable hash mode:

{
  "mcpServers": {
    "octofs": {
      "command": "octofs",
      "args": ["mcp", "--line-mode", "hash"]
    }
  }
}

Hint Modes

Octofs detects shell misuse — commands like cat, grep, find, or sed that should use the dedicated MCP tools instead — and enforces it in two modes:

Hard Mode (default)

The command is rejected with an error explaining which tool to use instead. The call fails; nothing executes.

Soft Mode

The command runs anyway, and the guidance is appended to the tool response as a ⚠️ hint.

Enable soft mode:

{
  "mcpServers": {
    "octofs": {
      "command": "octofs",
      "args": ["mcp", "--hint-mode", "soft"]
    }
  }
}

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.

octofs mcp --bind 0.0.0.0:12345

Connect clients to http://localhost:12345/mcp.

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 host
octofs mcp --path ssh://deploy@example.com/var/www/app --ssh-key ~/.ssh/id_ed25519

view path="ssh://deploy@example.com/etc/nginx/nginx.conf"

• Authentication — fully automatic, like OpenSSH, honoring ~/.ssh/config: the agent your config names for the host (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). If plain ssh host works on your machine, octofs works too — nothing to configure. 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 hashes)

{"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": "a3bd", "end": "c7f2"}  // hash mode

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

Directory listing:

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

pattern is a glob, not a content search: without / it matches the whole filename at any depth; with / it matches the workdir-relative path. It supports *, ?, character classes such as [abc], and | alternatives such as *.rs|*.toml.

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}

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:

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

Delete file: (recoverable with undo_edit)

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

Undo last edit:

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

---

batch_edit — Atomic multi-operation edits

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

Each operation has a start (line number or hash). For insert it's the anchor (0 = file start, -1 = after last line, N = after line N). For replace add end for a range (omit end for a single line). start and end must be the same kind — both line numbers or both hashes (no mixing).

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, "end": 15, "content": "new code here"}
  ]
}

Hash mode (stable across edits):

{
  "path": "src/main.rs",
  "operations": [
    {"operation": "replace", "start": "a3bd", "end": "c7f2", "content": "new code"}
  ]
}

---

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, from_end, and append_line each accept a line number or a content hash. append_line positions the copy in the target: 0 = beginning, -1 = end, N = after line N.

---

shell — Execute commands

Foreground:

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

Background:

{"command": "python -m http.server 8000", "background": true}
// Returns PID; the response includes the platform-specific kill command

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, HintMode
│   │   ├── 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         # LineMode, FNV-1a hashes, endpoint parsing
│       └── truncation.rs        # Token estimation, smart truncation

Key design decisions:

• rmcp SDK — Official Rust MCP SDK (rmcp 3.0) 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 — io_fingerprint comparison fails edits if the file changed on disk since last view

---

Development

# Build
cargo build --release

# Run tests
cargo test

# Lint (zero warnings policy)
cargo clippy

# Format
cargo fmt

# Run locally
cargo run -- mcp

Running Tests

# All tests
cargo test

# Specific test
cargo test test_view_file

# With output
cargo 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

---