fff (Fast File Finder)

FFF is a high-performance file search library designed for long-lived processes like IDE extensions or AI agents. Unlike CLI tools like ripgrep or fzf that fork a new process for every search, FFF keeps the index and file cache resident in memory, enabling sub-10ms queries on large repositories (e.g., 500k files).

Key Features:

• Frecency-ranked fuzzy matching: Ranks results based on access and modification frequency.
• Typo-resistant matching: Uses Smith-Waterman fuzzy scoring for both paths and content.
• Three Content Grep Modes: Plain literal (SIMD memmem), regex, and fuzzy (Smith-Waterman per line).
• Git Awareness: Returns gitStatus (modified, staged, untracked, ignored) without shelling out to the git CLI.
• Definition Classifier: Tags lines starting with keywords like struct, fn, class, def, and impl.
• Background Indexing: Uses a file watcher to update the index incrementally.

The fff.picker_ui module uses a coordinator pattern with shared state:

• Coordinator Pattern: picker_ui.lua acts as the coordinator, initializing submodules via module.init(parent_module). This allows submodules to call back into the coordinator for cross-module coordination (e.g., navigation.lua calling P.render_list()).
• Shared State: All submodules share a single source of truth via the picker_ui_state.state table. There is no message passing or event bus; modules read from and write to this shared table directly.
• Module Types:
  • Managers: (e.g., search_manager, preview_manager) Manage state or lifecycle.
  • Behavioral: (e.g., navigation, renderer) Handle specific actions or logic.
  • Renderers: (e.g., file_renderer, grep_renderer) Handle rendering of specific item types.
  • Pure Data/Utils: (e.g., picker_ui_state, utils) Standalone modules without parent references or cross-module dependencies.

The C library provides a stable ABI for binding from C/C++, Zig, Go, Python, etc.

Build:

# Builds only the C cdylib:
make build-c-lib

# Or with cargo (requires Zig for zlob feature):
cargo build --release -p fff-c --features zlob

Installation:

# System-wide:
sudo make install

# User-local:
make install PREFIX=$HOME/.local

Minimal C Example:

#include <fff.h>
#include <stdio.h>

int main(void) {
    FffResult *res = fff_create_instance(
        ".",        // base_path
        "",         // frecency_db_path
        "",         // history_db_path
        false,      // use_unsafe_no_lock
        true,       // enable_mmap_cache
        true,       // enable_content_indexing
        true,       // watch
        false       // ai_mode
    );
    if (!res->success) {
        fprintf(stderr, "init failed: %s\n", res->error);
        fff_free_result(res);
        return 1;
    }
    void *handle = res->handle;
    fff_free_result(res);

    // Search
    FffResult *search = fff_search(handle, "main.rs", "", 0, 0, 20, 100, 3);
    // ... read FffSearchResult from search->handle, then fff_free_search_result()

    fff_destroy(handle);
    return 0;
}

Important Notes:

• Functions returning FffResult* allocate with Rust's Box. Use fff_free_result to free them.
• Use FffCreateOptions (versioned struct) for preferred instance creation to avoid ABI breaks.
• Use fff_glob for literal glob searches that bypass the query parser.

You can install fff.nvim using lazy.nvim or vim.pack.

Using lazy.nvim:

{
  'dmtrKovalenko/fff.nvim',
  build = function()
    require("fff.download").download_or_build_binary()
  end,
  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',
    },
    { "fw", function() require('fff').live_grep_under_cursor() end,
      mode = { 'n', 'x' },
      desc = 'Search current word / selection',
    },
  },
}

Using vim.pack:

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

vim.api.nvim_create_autocmd('PackChanged', {
  callback = function(ev)
    local name, kind = ev.data.spec.name, ev.data.kind
    if name == 'fff.nvim' and (kind == 'install' or kind == 'update') then
      if not ev.data.active then vim.cmd.packadd('fff.nvim') end
      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' })