fff

一个面向人类和 AI Agent 的文件搜索工具包。速度极快。

具备抗拼写错误的路径与内容搜索、基于“最近最频繁”（frecency）排名的文件访问、后台监视器以及轻量级内存内容索引。在任何需要多次搜索的长期运行进程中，其速度远超 ripgrep 和 fzf 等 CLI 工具。

该项目最初是作为一个备受欢迎的 Neovim 插件 开发的，但后来发现许多 AI 工具和代码编辑器都有同样的需求：需要一个准确、快速的文件搜索库。这正是 fff 的定位。

---

选择你感兴趣的内容：

MCP Server

适用于 Claude Code、Codex、OpenCode、Cursor、Cline 以及任何支持 MCP 的客户端。减少 grep 的往返次数，降低上下文浪费，获取更快的回复。

一键安装

Linux / macOS:

curl -L https://dmtrkovalenko.dev/install-fff-mcp.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/dmtrKovalenko/fff.nvim/main/install-mcp.ps1 | iex

如果你想先阅读脚本，可以查看 install-mcp.sh 和 install-mcp.ps1。

脚本会打印出针对你客户端的具体配置说明。服务器连接成功后，只需让 Agent “use fff”，它就会自动调用 ffgrep、fffind 和 fff-multi-grep 工具。

推荐 Agent 提示词

将其添加到项目的 CLAUDE.md 或等效文件中：

For any file search or grep in the current git-indexed directory, use fff tools.

改进点

• Frecency 内存：你实际打开过的文件在下次搜索时排名更高。Git 的触碰历史记录会自动进行预热。
• 定义优先提示：看起来像代码定义的行会在 Rust 端进行分类，无需在提示词中进行正则处理。
• 智能大小写匹配（Smart-case）及模糊匹配自动回退：IsOffTheRecord 可以找到 snake_case 变体；无匹配查询时会自动重试模糊匹配，并展示最佳近似结果。
• Git 感知标注：已修改、未追踪和暂存的文件会被打上标签，以便 Agent 能优先处理你正在更改的内容。

源码：crates/fff-mcp/。

MCP Server 为任何 Agent 提供了一种比内置工具更快、更节省 Token 的文件搜索方案。

Pi Agent 扩展

安装

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

模式

提供三种运行模式，可在运行时通过 /fff-mode 切换：

模式	功能描述
tools-and-ui (默认)	添加 ffgrep 和 fffind 工具，并将 @-mention 自动补全替换为 FFF。
tools-only	仅注入工具。保留 pi 原生的编辑器自动补全。
override	使用 FFF 实现替换 pi 内置的 grep、find 和 multi_grep。

环境变量：PI_FFF_MODE, FFF_FRECENCY_DB, FFF_HISTORY_DB。 命令行参数：--fff-mode, --fff-frecency-db, --fff-history-db。

面向 Agent 的工具

• ffgrep: 内容搜索。接受 path、exclude（逗号、空格或数组；前导 ! 可选）、caseSensitive、context 以及游标分页。自动检测正则表达式，零完全匹配时回退到模糊搜索，并在预检阶段拒绝 .* 样式的通配符查询。
• fffind: 路径和文件名搜索。匹配整个仓库路径，而不仅仅是文件名。具备 Frecency 感知能力。弱匹配检测器会在模糊搜索结果淹没 Agent 上下文之前对其进行过滤。

命令

• /fff-mode [tools-and-ui | tools-only | override]: 查看或切换模式。
• /fff-health: 查看搜索器、Frecency 和 Git 集成状态。
• /fff-rescan: 强制重新扫描。

源码：packages/pi-fff/。

Pi 扩展将 pi 的原生工具替换为 FFF 实现，并利用基于 Frecency 排序的索引来填充交互式编辑器的 @-mention 自动补全。

fff.nvim

Linux 内核仓库演示（10 万个文件，8GB）：

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

安装

lazy.nvim

{
  'dmtrKovalenko/fff.nvim',
  build = function()
    -- 下载预构建的二进制文件或回退到 cargo build
    require("fff.download").download_or_build_binary()
  end,
  -- 对于 nixos:
  -- build = "nix run .#release",
  opts = {
    debug = {
      enabled = true,
      show_scores = true,
    },
  },
  lazy = false, -- 插件自动初始化
  keys = {
    { "ff", function() require('fff').find_files() end, desc = 'FFFind files' },
    { "fg", function() require('fff').live_grep() end, desc = 'LiFFFe grep' },
    { "fz",
      function() require('fff').live_grep({ grep = { modes = { 'fuzzy', 'plain' } } }) end,
      desc = 'Live fffuzy grep',
    },
    { "fc",
      function() require('fff').live_grep({ query = vim.fn.expand("") }) end,
      desc = 'Search current