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

Pre-built Binaries

Download from GitHub Releases for your platform:

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