dmtrKovalenko/fff

fff – Fast File‑Search Toolkit

What it is – fff is a Rust‑based library (with a tiny binary) that builds an in‑memory index of a code‑base and then serves ultra‑fast, typo‑tolerant file‑name and content searches. It is designed to be used by both humans (via a Neovim UI) and AI agents that need to look up files without sending huge amounts of text to the model.

Key features

• Typo‑resistant search – fuzzy matching on both paths and file contents.
• Frequency‑ranked (frecency) results – files you open often or have been touched recently are scored higher.
• Background watcher – the index updates automatically as files change, with Git‑aware annotations (modified, staged, recent commits).
• Lightweight in‑memory index – faster than ripgrep/fzf when the same repository is searched repeatedly.
• Multiple front‑ends:
  • fff.nvim – a Neovim plugin exposing picker UI and a Lua API (find_files, live_grep, etc.).
  • MCP server – a small binary (fff-mcp) that implements the MCP protocol used by Claude Code, Cursor, OpenCode, etc., giving agents tools like ffgrep and fffind.
  • Pi extension – a plugin for the Pi AI‑assistant that can replace its built‑in grep/find tools.

How it works

1. On first use a background process scans the configured root directory, builds a Rust index, and stores optional SQLite‑style databases for frecency and query history.
2. Subsequent searches query this index directly in RAM, avoiding the disk‑heavy round‑trips of traditional CLI greps.
3. The index is kept up‑to‑date by a file‑system watcher; Git status is added by reading the repository’s git metadata.
4. The library exposes two core Rust functions that the front‑ends call:
   • file_search(query, opts) – returns a list of files/directories with scores, frecency data, and Git flags.
   • content_search(query, opts) – returns line‑level matches with optional regex, fuzzy fallback, and smart‑case handling.

Typical usage

• In Neovim, press ff to open the FFFind picker, fg for live grep, or call the Lua API from a plugin.
• For an AI‑assistant, install the MCP server (brew install dmtrKovalenko/fff/fff-mcp or run the provided install script) and add it to the assistant’s config. The assistant can then invoke ffgrep/fffind as part of its toolset.
• With Pi, run pi install npm:@ff-labs/pi-fff and switch modes with /fff-mode.

Why it matters for AI/LLM workflows Large language models have limited context windows. By letting the model ask a fast, token‑efficient file‑search service, you avoid sending the whole repository to the model and keep the interaction snappy. The frecency and Git‑aware scoring also help the model surface the most relevant files first, reducing hallucinations.

Installation highlights

• One‑line script for the MCP server (curl … | bash on Linux/macOS, PowerShell on Windows).
• Homebrew formula (brew install dmtrKovalenko/fff/fff-mcp).
• Neovim – add dmtrKovalenko/fff to your plugin manager; the plugin will download a pre‑built binary or compile it with Cargo.
• Pi – pi install npm:@ff-labs/pi-fff.

License & sponsorship

• MIT‑licensed, open‑source forever.
• Sponsored by Anomaly (opencode.ai), Mango Proxy, and RapidProxy.

---

All details above are taken directly from the repository’s README.