Skip to content
Get packs

Guide · Open source

How to use fff: install the MCP server and search files

Updated · written with AI from the project's own documentation and checked against our catalogue data

fff is an open-source file search toolkit for developers and AI agents. It finds files by path, searches file contents while tolerating typos, and keeps an in-memory index that stays fast in a long-running process. This guide shows how to install the MCP server with Homebrew, connect it to Codex, and understand the main search tools so you can use it well.

fffdmtrKovalenko/fff · ★ 11.2k · MIT

Quick start

  1. 1Check Homebrew. Confirm Homebrew is installed on your macOS or Linux machine, since the Homebrew route needs it.
  2. 2Install fff-mcp. Run brew install dmtrKovalenko/fff/fff-mcp to install the prebuilt MCP server binary.
  3. 3Register with Codex. Run codex mcp add fff with the absolute path from brew --prefix so Codex can find the binary.
  4. 4Restart the client. Restart Codex or start a new task so it loads the fff server.
  5. 5Ask the agent to use fff. Prompt the agent with "use fff" to confirm the tools are available.
  6. 6Scope your searches. Pass path or globs to narrow results to the directory or file types you need.

What fff does and who it is for

fff is a file search toolkit. Its README describes typo-resistant path and content search, frequency-ranked file access, a background watcher, and a lightweight in-memory content index. The project started as a Neovim plugin and was later packaged as a library for AI harnesses and code editors.

It ships as an SDK for Rust, Python, Node.js, Bun and C, a Neovim plugin, and an MCP server that AI coding agents can call. The README says the speed advantage appears in long-running processes that search more than once.

  • Good fit: developers building an AI coding agent or editor, Neovim users who want fuzzy file and content search, and people using an MCP-capable client.
  • Probably not needed: a single one-off search in a terminal. The README notes that plain ripgrep or fzf may be enough there.
  • Not a desktop app: the project is described as a toolkit and SDK rather than a standalone end-user application.

Install the fff-mcp server with Homebrew

Homebrew is the install route covered in this guide, so you need Homebrew on macOS or Linux. The formula installs the prebuilt fff-mcp binary from the project's GitHub releases.

To update later, run the upgrade command after new stable releases.

  • The formula is kept in the repository at Formula/fff-mcp.rb and is bumped automatically on each stable release.
brew install dmtrKovalenko/fff/fff-mcp brew upgrade fff-mcp

Connect fff to Codex

Register the installed binary by its absolute path. The README explains that Codex desktop sessions may not inherit your interactive shell's PATH. Using $(brew --prefix) builds that path for you.

This command creates an entry in ~/.codex/config.toml. After registering, restart Codex or start a new task so it loads the server. Then ask the agent to "use fff".

  • Other clients named in the README include Claude Code, OpenCode, Cursor and Cline.
  • The one-line installer is also available for Linux, macOS and Windows; it places the binary at $HOME/.local/bin/fff-mcp on the Codex example path.
codex mcp add fff -- "$(brew --prefix)/bin/fff-mcp"

Know the three MCP tools

The MCP server exposes three tools: grep, find_files and multi_grep. grep searches file contents, find_files matches paths, and multi_grep handles several patterns in one call.

find_files matches path fragments before approximate filenames and treats hyphens and underscores alike by default. Setting mode to glob or regex gives exact path filtering.

  • Pass path to scope a search to a known file or directory, and globs for patterns.
  • Set definitions_only to true to search declarations, for example in src/audio.
  • Grep returns up to 100 matching lines per page by default, 30 with definitions_only, and at most 200. Use maxResults and the returned cursor to continue.
  • Set context: 0 to get matching lines only.
{ "query": "AudioMap", "path": "src/audio", "definitions_only": true }

Write a regex search with scope and globs

The MCP server accepts ripgrep-style searches without putting scope tokens inside the pattern. Use mode regex or literal to preserve the query exactly, including whitespace. Matching is case-sensitive by default, and case also accepts insensitive or smart.

Positive globs act as alternatives, and exclusions take priority. hidden: false skips hidden paths unless a path or glob explicitly includes them. Globs cannot bring back files the index's ignore rules exclude.

  • Regex matches stay within one line unless the pattern contains \n.
  • Supplying paths or globs keeps the query verbatim, so inline constraint tokens are treated as search text.
{"query":"retry|backoff","mode":"regex","paths":["src","lib"],"globs":["*.rs","!**/tests/**"],"context":3}

Add a search prompt to your project

The README suggests adding an instruction to your project's CLAUDE.md or an equivalent agent instructions file. The suggested prompt tells the agent to use fff for file search in the current git-indexed directory, to include the known directory in the first search, and to read more source only when needed.

If a definition search finds nothing exact, fff tries fuzzy declaration matches and labels them "Maybe you meant these definitions". Filename-only suggestions from a broader search are labeled as unverified.

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.

What people use it for

  • An AI coding agent searching a codebase through a resident index across tool calls.
  • Searching for a function or class declaration with definitions_only in a known module.
  • Regex searches across selected source folders while excluding test directories with globs.
  • Embedding file search in a Rust, Python, Node.js or Bun application using the SDK.
  • Fuzzy file and content search inside Neovim using the plugin.

Frequently asked questions

Is fff free to use?

The project is released under the MIT licence, according to the README and repository summary. The README states that fff is MIT and open source.

What do I need to install fff-mcp?

The Homebrew route requires Homebrew on macOS or Linux. Run brew install dmtrKovalenko/fff/fff-mcp to install the prebuilt binary.

How do I connect fff to Codex?

Run codex mcp add fff -- "$(brew --prefix)/bin/fff-mcp", then restart Codex or start a new task so it loads the server.

Is fff faster than ripgrep or fzf?

The README says fff is much faster than CLIs like ripgrep and fzf in long-running processes that search more than once. For a single one-off search, it notes that ripgrep or fzf may be enough.

What are the main fff MCP tools?

The MCP tools are grep, find_files and multi_grep. grep searches file contents, and find_files matches file paths.

What is the alternative if I only need a quick terminal search?

For a one-off terminal search, the README points to ripgrep or fzf. Related tools named in the source include fd and telescope.nvim.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

fff suits developers building AI coding agents or editors, Neovim users wanting fuzzy file and content search, and teams embedding search in Rust, Python, Node.js or Bun. If you only need occasional terminal searches or a polished desktop app, ripgrep, fzf or fd may serve you better.

Install options & downloads