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/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 — 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. 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.

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: