fff (Fast File Finder)

Overview

Blazing-fast file search built in Rust, designed for AI agents and editor integration. Searches millions of files in milliseconds with fuzzy matching, regex, and smart filtering. Available as a CLI, Node.js API, and Neovim plugin.

Instructions

Installation

Rust CLI:

cargo install fff-search

Node.js API:

npm install fff-search

Neovim Plugin (lazy.nvim):

{
  "fff-nvim/fff.nvim",
  build = "cargo build --release",
  config = function()
    require("fff").setup({
      respect_gitignore = true,
      hidden_files = false,
      max_results = 100,
      fuzzy_threshold = 0.6,
    })
  end,
  keys = {
    { "<leader>ff", "<cmd>FffFind<cr>",   desc = "Find files (fff)" },
    { "<leader>fg", "<cmd>FffGrep<cr>",   desc = "Grep content (fff)" },
    { "<leader>fr", "<cmd>FffRecent<cr>", desc = "Recent files (fff)" },
  },
}

CLI Usage

fff "component"                    # Basic fuzzy search
fff "handler" --dir ./src          # Search in specific directory
fff --regex "test_.*\.py$"         # Regex search
fff --grep "TODO|FIXME" --dir .    # Search file contents
fff "config" --hidden              # Include hidden files
fff "utils" --max-results 20       # Limit results
fff "service" --json               # JSON output (for AI agents)
fff "schema" --ext ts,tsx          # Filter by extension
fff "MyClass" --case-sensitive     # Case-sensitive search

Node.js API

const { FffSearch } = require("fff-search");

const searcher = new FffSearch({
  rootDir: process.cwd(),
  respectGitignore: true,
  hiddenFiles: false,
});

// Fuzzy file search
const results = await searcher.find("component", { maxResults: 10, threshold: 0.6 });

// Grep file contents
const grepResults = await searcher.grep("TODO", { extensions: ["ts", "js"], maxResults: 100 });

Neovim Commands

:FffFind [query]    — Fuzzy file search (replaces Telescope find_files)
:FffGrep [pattern]  — Search file contents (replaces Telescope live_grep)
:FffRecent          — Recently opened/modified files
:FffBuffer          — Search open buffers
:FffGitFiles        — Search git-tracked files only

Examples

Example 1: AI Agent Tool Integration

User request: "Set up fff as a file search tool for an AI agent."

Implementation:

const fileSearchTool = {
  name: "search_files",
  description: "Search for files by name or content in the project",
  parameters: {
    query:      { type: "string", description: "Search query (fuzzy or regex)" },
    mode:       { type: "string", enum: ["filename", "content"], default: "filename" },
    extensions: { type: "array", items: { type: "string" }, optional: true },
  },
  execute: async ({ query, mode, extensions }) => {
    const searcher = new FffSearch({ rootDir: process.cwd() });
    if (mode === "content") {
      return searcher.grep(query, { extensions, maxResults: 20 });
    }
    return searcher.find(query, { maxResults: 20 });
  },
};

Example 2: JSON Output for LLM Consumption

User request: "Find all handler files and return structured results."

$ fff "handler" --json
[
  {
    "path": "src/api/handler.ts",
    "score": 0.95,
    "line": null,
    "modified": "2024-03-15T10:30:00Z"
  },
  {
    "path": "src/ws/messageHandler.ts",
    "score": 0.82,
    "line": null,
    "modified": "2024-03-14T08:15:00Z"
  }
]

Guidelines

• Use --json output for structured results parseable by LLMs and AI agents
• Enable background indexing ([index] enabled = true in config) for instant results in large repos
• Use --dir to scope search to specific packages in monorepos
• fff replaces Telescope's file finder in Neovim with 10-50x faster results
• Use --ext to narrow searches by file type when working in polyglot repos
• Configure ~/.config/fff/config.toml for persistent settings (gitignore, hidden files, max results)