ffs — Fast File Search

A code-aware file search CLI for humans and AI agents. Really fast.
Replaces find + grep + glob + cat + tree-sitter with one binary. Typo-tolerant fuzzy matching, frecency ranking, token-budget reader, MCP server.

curl -fsSL "https://raw.githubusercontent.com/quangdang46/fast_file_search/main/install.sh?$(date +%s)" | bash

🤖 Agent Quickstart (MCP / Robot Mode)

ffs ships a 15-tool MCP server over stdio. The installer auto-configures it for Claude Code, Codex, Cursor, Windsurf, Gemini, OpenCode, and more.

# Run as MCP server
ffs mcp

# Agent-friendly JSON queries
ffs grep 'fn main' --format json
ffs symbol FilePicker --format json
ffs read crates/ffs-engine/src/lib.rs --budget 5000 --format json
ffs map --depth 3 --format json
ffs overview --format json
ffs deps path/to/file.rs --format json

Output conventions

• stdout = structured data (JSON or text)
• stderr = diagnostics, warnings
• exit 0 = success

MCP tools exposed: ffs_find, ffs_grep, ffs_multi_grep, ffs_symbol, ffs_callers, ffs_callees, ffs_refs, ffs_flow, ffs_impact, ffs_outline, ffs_siblings, ffs_deps, ffs_map, ffs_overview, ffs_read

TL;DR

The Problem

File search and code navigation require a menagerie of tools: find, fd, grep, rg, glob, cat, plus a tree-sitter plugin for symbol queries. Each has different syntax, different startup cost, different output formats. AI agents struggle with this combinatorial explosion of invocation patterns — and every pipeline hop loses milliseconds that add up across hundreds of queries.

The Solution

ffs replaces all of them with a single binary that understands code. Typo-resistant fuzzy matching, frecency-ranked results, tree-sitter-powered symbol/callers/callees/refs queries, and a token-budget aware file reader — all from one executable that starts in milliseconds and keeps a warm cache for sub-10 ms subsequent calls.

Why ffs?

How ffs Compares

Quick Example

# Index once, query forever
ffs index                                     # ~200 ms on 10k-file repo
ffs find UnifiedScanner                       # fuzzy file-name search
ffs find grep --scored                        # role-aware ranking
ffs grep '\bTODO\b' --root crates/            # content grep
ffs grep 'fn main' --group                    # symbol-grouped grep
ffs multi-grep TODO FIXME HACK                # multi-literal OR (Aho-Corasick)
ffs symbol FilePicker                         # tree-sitter symbol lookup
ffs callers UnifiedScanner                    # who calls a symbol
ffs read crates/ffs-engine/src/lib.rs --budget 5000  # token-budget reader
ffs map --depth 3                             # workspace tree
ffs mcp                                       # run as MCP server over stdio
ffs mcp /path/to/workspace                    # pin MCP index root explicitly

MCP workspace root. When launched without a path (as installers do for Cursor/VS Code), ffs mcp resolves the root from, in order: WORKSPACE_FOLDER_PATHS (injected by Cursor/VS Code), VSCODE_CWD, then cwd. User-level ~/.cursor/mcp.json with args: ["mcp"] therefore indexes the open workspace, not the home directory. Prefer an explicit path (args: ["mcp", "${workspaceFolder}"]) in project-level configs when available.

Design Philosophy

Installation

# macOS / Linux — curl pipe
curl -fsSL "https://raw.githubusercontent.com/quangdang46/fast_file_search/main/install.sh?$(date +%s)" | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/quangdang46/fast_file_search/main/install.ps1 | iex

# From source (with zlib compression support)
cargo build --release -p ffs-cli --features zlib
./target/release/ffs --version

The installers detect platform, fetch the matching release binary, verify SHA-256 sidecar, and atomically install to ~/.local/bin/ffs. MCP server configs are auto-detected for Claude Code, Codex, Cursor, Windsurf, VS Code, Gemini, OpenCode, and more.

Supported platforms

Linux x86_64/aarch64, macOS x86_64/aarch64, Windows x86_64/aarch64

Commands

Performance

All numbers are single-threaded medians on Linux x86-64 (Criterion.rs).

Engine dispatch (256-file fixture)

Bigram index

Symbol index (1 K files)

Architecture

┌──────────────────────────────────────┐
│  Frontends                            │
│  ffs-cli (binary) · ffs-mcp (MCP)    │
│  ffs-c (C ABI .so/.dylib/.dll)        │
└──────────────┬───────────────────────┘
               │ all surfaces share one core
               ▼
┌──────────────────────────────────────┐
│  Engine layer                         │
│  ffs-engine — dispatch · ranking      │
│  ffs-query-parser — DSL + constraints  │
└──────────────┬───────────────────────┘
               ▼
┌──────────────────────────────────────┐
│  Capability layer                     │
│  ffs-symbol — tree-sitter · bloom     │
│  ffs-grep — SIMD literal / regex      │
│  ffs-budget — token-aware reader      │
└──────────────┬───────────────────────┘
               ▼
┌──────────────────────────────────────┐
│  Core layer (ffs-core)                │
│  scan · file_picker · score · git      │
│  frecency · watcher · ignore           │
└──────────────────────────────────────┘

Troubleshooting

Limitations

FAQ

Does ffs need a pre-built index?

Yes — run ffs index once per repo. The index is cached in <repo>/.ffs/ and auto-invalidates on schema bumps, git HEAD changes, or significant file-count drift.

Can I use ffs as a library from Rust?

Yes — all crates publish via ffs-*. The C ABI (ffs-c) is stable for foreign bindings (Python, Node.js, etc.).

What's the difference between ffs callers and ffs refs?

callers lists call sites (who invokes a symbol). refs combines definitions and usages in one shot — both call sites and other references.

Does ffs work on non-git directories?

Yes — it falls back to a full filesystem scan. Some features (frecency warm-up, cache invalidation) require git.

MCP vs CLI — which should agents use?

Prefer ffs mcp for agent contexts — 15 tools via stdio JSON-RPC, no parsing required. Use CLI with --format json for one-shot queries.