fff

A file search toolkit for humans and AI agents. Really fast.

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 these companies:

Use and enjoy fff? Become a sponsor to get your features/fixes the highest priority.

Pick what you are interested in:

MCP server

Works with Claude Code, Codex, OpenCode, Cursor, Cline, and any MCP-capable client. Fewer grep roundtrips, less wasted context, faster answers.

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.

Once the server is connected, ask the agent to "use fff" and it picks up the ffgrep, fffind, and fff-multi-grep tools.

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.

What changes

• Frecency memory. Files you actually open rank higher next time. Warm-up from git touch history runs automatically.
• Definition-first hinting. Lines that look like code definitions are classified on the Rust side, no regex overhead in your prompt.
• Smart-case with auto-fuzzy fallback. IsOffTheRecord finds snake_case variants; zero-match queries retry as fuzzy and surface the best approximate hits.
• Git-aware annotations. Modified, untracked, and staged files are tagged so the agent reaches for what you are actively changing.

Source: crates/fff-mcp/.

The MCP server gives any agent a file search tool that is faster and more token-efficient than the built-in one.

Pi agent extension

Install

pi install npm:@ff-labs/pi-fff

Modes

Three operating modes, switchable at runtime with /fff-mode:

Env vars: PI_FFF_MODE, FFF_FRECENCY_DB, FFF_HISTORY_DB. Flags: --fff-mode, --fff-frecency-db, --fff-history-db. The databases default to your existing fff.nvim ones when present, otherwise ~/.pi/agent/fff/.

Agent-facing tools

• ffgrep. Content search. Accepts path, exclude (comma, space, or array; leading ! optional), caseSensitive, context, and cursor pagination. Auto-detects regex, falls back to fuzzy on zero exact matches, rejects .*-style wildcard-only patterns up front.
• fffind. Path and filename search. Matches the whole repo-relative path, not just the filename. Frecency-aware. The weak-match detector flags scattered fuzzy noise before it floods the agent's context.

Commands

• /fff-mode [tools-and-ui | tools-only | override]. Show or switch the mode.
• /fff-health. Picker, frecency, and git integration status.
• /fff-rescan. Force a rescan.

Source: packages/pi-fff/.

The Pi extension swaps pi's native tools for FFF implementations and feeds the interactive editor's @-mention autocomplete from the frecency-ranked index.

fff.nvim

Demo on the Linux kernel repo (100k files, 8GB):

https://github.com/user-attachments/assets/5d0e1ce9-642c-4c44-aa88-01b05bb86abb

Installation

lazy.nvim

…

vim.pack

…

Public API

…

file_search(query, opts)

Returns a structured result { items, scores, total_matched, total_files?, total_dirs?, location? }. Each item has a type field ("file" or "directory") and name / relative_path. File items also expose size, modified, git_status, is_binary, and frecency scores.

local r = require('fff').file_search('button', {
  mode             = 'mixed',  -- 'files' (default) | 'directories' | 'mixed'
  max_results      = 50,
  page             = 0,        -- 0-based pagination
  current_file     = nil,      -- path to deprioritize for distance scoring
  max_threads      = 4,
  cwd              = nil,      -- switch indexed root if different (see below)
  wait_for_index_ms = nil,     -- override the default scan wait timeout
})
for _, item in ipairs(r.items) do
  print(item.type, item.relative_path)
end

content_search(query, opts)

Returns a GrepResult { items, total_matched, total_files_searched, total_files, filtered_file_count, next_file_offset, regex_fallback_error? }. Each match item has relative_path, name, line_number, col, line_content, match_ranges, plus the same file metadata as file_search.

…

Both functions accept the same constraint syntax as the UI pickers (e.g. git:modified, *.rs, !test/, glob patterns).

cwd and indexing

Both file_search and content_search honour an optional cwd field. The first call to either function lazily initialises the picker at config.base_path (your Neovim cwd by default).

• If cwd matches the currently indexed root, the call returns immediately against the existing index.
• If cwd differs, the picker is re-indexed at the new root and the call blocks (default up to 10 s) until the new picker is installed and its initial scan completes — so callers always get results from the right tree.
• If the index is still warming up after a change_indexing_directory, you can pass wait_for_index_ms = N to block for up to N ms regardless of whether cwd triggered the swap. Pass 0 to skip waiting entirely (useful for fire-and-forget calls where partial results are acceptable).
• Invalid or non-existent cwd paths return an empty result and emit an error via vim.notify.

Autocmds

The picker fires User autocmds when it opens and closes. FFFOpen runs with the prompt window focused, FFFClose runs after every picker window is gone — so hide global UI, not window-local options of the picker itself:

vim.api.nvim_create_autocmd('User', {
  pattern = { 'FFFOpen', 'FFFClose' },
  callback = function(ev) vim.o.showtabline = ev.match == 'FFFOpen' and 0 or 2 end,
})

Commands

• :FFFScan. Rescan files.
• :FFFRefreshGit. Refresh git status.
• :FFFClearCache [all|frecency|files]. Clear caches.
• :FFFHealth. Health check.
• :FFFDebug [on|off|toggle]. Toggle the scoring display.
• :FFFOpenLog. Open ~/.local/state/nvim/log/fff.log.

Configuration

Defaults are sensible. Override only what you care about.

…

Live grep modes

<S-Tab> cycles between plain, regex, and fuzzy. The list is configurable via grep.modes, and single-mode setups hide the indicator entirely.

Per-call override:

require('fff').live_grep({ grep = { modes = { 'fuzzy', 'plain' } } })
require('fff').live_grep({ query = 'search term' }) -- pre-fill

Constraints

Both find and grep accept these tokens to refine a query:

• git:modified. One of modified, staged, deleted, renamed, untracked, ignored.
• test/. Any deeply nested children of test/.
• !something, !test/, !git:modified. Exclusion. Text exclusions need at least 3 alphanumeric-containing characters, so operators like != or !== work.
• ./**/*.{rs,lua}. Any valid glob, powered by zlob.

Grep-only:

• *.md, *.{c,h}. Extension filter.
• src/main.rs. Grep inside a single file.

Mix freely: git:modified src/**/*.rs !src/**/mod.rs user controller.

Open in invoking window

By default fff.nvim will try to open a file in the most suitable window, so any non-file buffers are not affected. You can customize or disable this by providing:

require('fff').setup({
  select = {
    select_window = function(_current_buf, _action) return nil end,
  },
})

Caveat: the chosen file replaces the buffer in the invoking window even if it's a non-modifiable / special buftype. winfixbuf windows still fall back to :split to avoid E1513.

Multi-select and quickfix

• <Tab>. Toggle selection (shows a thick ▊ in the signcolumn).
• <C-q>. Send selected files to the quickfix list and close the picker.

Git status highlighting

Sign-column indicators are on by default. To color filename text by git status, set git.status_text_color = true and adjust the hl.git_* groups. See :help fff.nvim for the full list.

Float colors

The picker maps its float content to NormalFloat (via hl.normal) and the border to FloatBorder. Default FloatBorder links to NormalFloat, so border and content share a background out of the box and the picker reads