Typo-resistant path and content search, frequency-ranked file access, a background watcher, and a lightweight in-memory content index. Way faster than CLIs like ripgrep and fzf in any long-running process that searches more than once.
Powers file search in opencode, nushell, and many more amazing projects!
Originally started as Neovim plugin people loved, but it turned out that plenty of AI harnesses and code editors need the same thing: accurate, fast file search as a library. That is what fff is.
Sponsors
fff is MIT and open source forever. Development is supported by:
Use and enjoy fff? Become a sponsor to get your features/fixes the highest priority.
Pick what you are interested in:
Works with Claude Code, Codex, OpenCode, Cursor, Cline, and any MCP-capable client. A resident Rust index supports file discovery and content search across tool calls.
The chart compares warm FFF MCP with shell search in the small and big repos. Startup and indexing are excluded.
Six additional tasks were held out from tuning in the small repo. The big repo appears in the main comparison above, but did not have a separate held-out run.
| Held-out model | Shell time | FFF time | Shell tokens | FFF tokens |
|---|
| Opus 5.5 | 10.7 s | 9.0 s | 58.3k | 49.2k |
| GPT-6 Astra | 8.1 s | 9.0 s | 43.9k | 49.3k |
Held-out chart. Both models returned all six expected answers in each recorded search mode. Tokens include cached input.
One-line install
Linux / macOS:
curl -L https://dmtrkovalenko.dev/install-fff-mcp.sh | bash
Windows (PowerShell):
irm https://raw.githubusercontent.com/dmtrKovalenko/fff/main/install-mcp.ps1 | iex
The scripts live at install-mcp.sh and install-mcp.ps1 if you want to read them first. They print the exact wiring instructions for your client.
Homebrew (macOS / Linux)
brew install dmtrKovalenko/fff/fff-mcp
brew upgrade fff-mcp # after new stable releases
Formula lives in Formula/fff-mcp.rb in this repo and is auto-bumped on every stable release (see bump-homebrew-formula in .github/workflows/release.yaml). Installs the prebuilt fff-mcp binary from GitHub releases.
Codex setup
Register the installed binary using its absolute path, since Codex desktop sessions may not inherit your interactive shell's PATH.
Homebrew:
codex mcp add fff -- "$(brew --prefix)/bin/fff-mcp"
One-line installer:
codex mcp add fff -- "$HOME/.local/bin/fff-mcp"
This creates an entry in ~/.codex/config.toml similar to:
[mcp_servers.fff]
command = "/opt/homebrew/bin/fff-mcp"
Use the actual installed path for your system, then restart Codex or start a new task so it loads the server.
On Codex versions that support omit_tools_from, add omit_tools_from = ["deferred"] to this server's configuration to expose FFF's tools immediately. This avoids a separate tool-discovery round trip. The measurements above use this setting.
Once the server is connected, ask the agent to "use fff". The MCP tools are grep, find_files, and multi_grep.
Recommended agent prompt
Drop this into your project's CLAUDE.md or equivalent:
For any file search or grep in the current git-indexed directory, use fff tools.
Include the known directory or module in the first search. Use definitions_only
for declarations. Read more source only when the returned lines need context.
Definition search
MCP and Pi accept definitions_only: true to search declarations. MCP uses { "query": "AudioMap", "path": "src/audio", "definitions_only": true }; Pi's ffgrep uses pattern instead of query. In MCP, use path for a known file or directory and globs for patterns. MCP's path also scopes find_files. Inline query constraints remain supported.
An existing checkout-relative path anchors the search at the root; otherwise the name matches at any depth. Case or -/_ differences use the indexed spelling with a notice. Missing paths also produce a notice. A definition query drops a filename constraint that matches no indexed file and reports that change.
MCP also accepts ripgrep-style searches without putting scope tokens in the pattern:
{"query":"retry|backoff","mode":"regex","paths":["src","lib"],"globs":["*.rs","!**/tests/**"],"context":3}
mode: "regex" and mode: "literal" preserve the query, including whitespace, and default to case-sensitive matching. case also accepts "insensitive" and "smart". Without a mode, smart-case and inline constraints remain available. Supplying paths or globs keeps the query verbatim, so inline constraint tokens become search text. Regex matches stay within one line unless the pattern contains \n.
paths contains checkout-relative files or directories. Positive globs are alternatives; exclusions take priority. hidden: false skips hidden paths unless a path or glob explicitly includes them. Globs cannot restore files excluded by the index's ignore rules. Ripgrep-specific .rgignore files can also make its file inventory differ.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
