octofs

<div align="center">

# 🐙 Octofs

**Give your AI assistant filesystem superpowers**

[![CI](https://github.com/muvon/octofs/actions/workflows/ci.yml/badge.svg)](https://github.com/muvon/octofs/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmuvon%2Foctofs%2Fbadges%2Fcoverage.json&style=flat-square)](https://github.com/muvon/octofs/actions/workflows/ci.yml)
[![Rust](https://img.shields.io/badge/Rust-1.95+-orange.svg?logo=rust)](https://www.rust-lang.org)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-2026--07--28-green.svg)](https://modelcontextprotocol.io)
[![Version](https://img.shields.io/crates/v/octofs.svg)](https://crates.io/crates/octofs)

*Standalone Rust binary that exposes filesystem tools over the Model Context Protocol. Built on `rmcp` 3.x, `tokio`, and `axum`.*

[Installation](#installation) · [Quick Start](#quick-start) · [Features](#features) · [Tools Reference](#mcp-tools-reference) · [Docs](doc/tools.md) · [Architecture](#architecture) · [Changelog](CHANGELOG.md)

MCP Registry: [`io.github.Muvon/octofs`](https://registry.modelcontextprotocol.io)

</div>

---

## 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 Addressing** | Composite `N:hh` ids — hash-verified at apply time; stale edits fail with relocation hints | Number-only |
| **Transport** | STDIO + Streamable HTTP | STDIO only |
| **Shell Integration** | Automatic foreground-to-background handoff | Limited or none |
| **Remote Files** | Transparent SSH/SFTP on every file tool | None |
| **Re-reads** | Delta views — re-viewing a file returns only the hunks changed since | Full file every time |
| **Safety** | Gitignore-aware, stale-write detection, path validation | Full filesystem access |

---

## Installation

### Cargo (crates.io)

```bash
cargo install octofs
```

### Homebrew

```bash
brew install muvon/tap/octofs
```

### npm (no Rust toolchain needed)

```bash
npx -y @muvon/octofs --version
```

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

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

### Pre-built Binaries

Download from [GitHub Releases](https://github.com/muvon/octofs/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` |

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](https://registry.modelcontextprotocol.io) as `io.github.Muvon/octofs`.

### From Source

Requires Rust 1.95+.

```bash
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`):
```json
{
  "mcpServers": {
    "octofs": {
      "command": "octofs",
      "args": ["mcp"]
    }
  }
}
```

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
  "mcpServers": {
    "octofs": {
      "command": "octofs",
      "args": ["mcp"]
    }
  }
}
```

**Windsurf** (`~/.windsurf/mcp.json`):
```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](#remote-filesystem-sshsftp))

### ✏️ 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.

```bash
octofs mcp
```

#### HTTP

Streamable HTTP transport for remote access or multi-client scenarios.

```bash
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:

```json
{
  "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:

```bash
# Remote session root: rela