FFF

AI agents (MCP)   |   Neovim 用户

一个为您的 AI 和 Neovim 设计的快速文件搜索工具，内置记忆功能。

---

FFF 代表 freakin fast fuzzy file finder（任选三个单词），它是一个专为 AI Agent 和 Neovim 设计的、有明确立场（opinionated）的模糊文件选择器。它专注于文件搜索，且我们致力于将文件搜索做到极致。

FFF 是一个用于 grep、模糊文件匹配、globbing 和多重 grep 的工具，高度重视性能和搜索结果的实用性。对于人类用户，它提供了难以置信的抗拼写错误体验；对于 AI Agent，它实现了最快的文件搜索，并额外提供内置记忆功能，根据访问频率（frecency）、git 状态、文件大小、定义匹配等多种因素建议最佳搜索结果。

MCP

FFF 是减少 AI Agent 使用时间和 token 消耗的绝佳方式，通过为其文件搜索工具提供内置的记忆能力，使您的 AI 能够更快地找到代码，并通过减少往返次数和减少读取无用文件来节省 token。

您可以使用简单的 bash 脚本将 FFF 作为 AI Agent 的依赖项安装：

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

如果您想在运行前查看脚本，安装脚本位于此处：./install-mcp.sh。

它将打印出如何将其连接到您的 Claude Code、Codex、OpenCode 等工具的说明。连接完成后，只需让您的 Agent "use fff" 即可。 以下是一个可以完美运行的 CLAUDE.md 添加示例：

# CLAUDE.md
For any file search or grep in the current git indexed directory use fff tools

Neovim 指南

这里是在 linux 仓库（10k 个文件，8GB）上的演示，但您最好亲自尝试一下，见证其神奇之处：

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

安装

FFF.nvim 需要 neovim 0.10.0 或更高版本。

lazy.nvim

{
  'dmtrKovalenko/fff.nvim',
  build = function()
    -- 这将下载预编译的二进制文件，或者尝试使用现有的 rustup 工具链从源码构建
    -- (如果您使用 lazy，可以使用 gb 来重新构建插件)
    require("fff.download").download_or_build_binary()
  end,
  -- 如果您使用的是 nixos
  -- build = "nix run .#release",
  opts = { -- (可选)
    debug = {
      enabled = true,     -- 我们希望在测试版期间得到您的协作
      show_scores = true, -- 帮助我们优化评分系统，欢迎分享您的分数！
    },
  },
  -- 使用 lazy.nvim 不需要延迟加载。
  -- 此插件会自动进行延迟初始化。
  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 word',
    },
  }
}

vim.pack

vim.pack.add({ 'https://github.com/dmtrKovalenko/fff.nvim' })

vim.api.nvim_create_autocmd('PackChanged', {
  callback = function(event)
    if event.data.updated then
      require('fff.download').download_or_build_binary()
    end
  end,
})

-- 插件将自动延迟加载
vim.g.fff = {
  lazy_sync = true, -- 仅在打开选择器时开始同步
  debug = {
    enabled = true,
    show_scores = true,
  },
}

vim.keymap.set(
  'n',
  'ff',
  function() require('fff').find_files() end,
  { desc = 'FFFind files' }
)

配置

FFF.nvim 附带了合理的默认设置。以下是包含所有可用选项的完整配置：

require('fff').setup({
    base_path = vim.fn.getcwd(),
    prompt = '🪿 ',
    title = 'FFFiles',
    max_results = 100,
    max_threads = 4,
    lazy_sync = true, -- 如果希望在打开时就开始文件索引，请设置为 false
    layout = {
      height = 0.8,
      width = 0.8,
      prompt_position = 'bottom', -- 或 'top'
      preview_position = 'right', -- 或 'left', 'right', 'top', 'bottom'
      preview_size = 0.5,
      flex = { -- 设置为 false 可禁用 flex 布局
        size = 130, -- 列阈值：如果屏幕宽度 >= size，使用 preview_position；否则换行
        wrap = 'top', -- 当屏幕窄于 size 时使用的位置
      },
      show_scrollbar = true, -- 显示用于分页的滚动条
      -- 如何缩短文件列表中的长目录路径：
      -- 'middle_number' (默认): 使用点号表示 1-3 个隐藏目录 (a/./b, a/../b, a/.../b)
      --                            并使用数字表示 4 个以上 (a/.4./b, a/.5./b)
      -- 'middle': 始终截断
    }
})