fff.nvim Unique Features: A Deep Dive into the Rust-Powered Fuzzy File Picker

fff.nvim is a high-performance fuzzy file picker for Neovim 0.10+ that combines a Rust backend for millisecond-latency search with a Lua UI, offering unique capabilities like frecency-based ranking, three-mode live grep, cross-mode suggestions, and MCP support for AI agents.

fff.nvim is an opinionated fuzzy-file picker developed by dmtrKovalenko that redefines file navigation in Neovim. Unlike traditional Lua-based pickers, it delegates heavy computational work to a Rust binary while maintaining a flexible, highly configurable Lua interface. This architecture enables unique features such as intelligent history scoring, real-time Git status integration, and AI-agent compatibility that set it apart from Telescope or fzf-lua.

Rust-Powered Backend Architecture

The core distinguishing feature of fff.nvim is its hybrid Rust-Lua architecture implemented across several key modules. In lua/fff/fuzzy.lua (line 5), the plugin loads the native module via pcall(require, 'fff.rust'), creating a thin Lua façade that delegates all CPU-intensive operations to the Rust binary.

The initialization logic in lua/fff/core.lua ensures singleton behavior through the ensure_initialized() function (line 73). This function creates the Rust database connection via fuzzy.init_db and initializes the file picker through fuzzy.init_file_picker. An autocmd group fff_file_tracking (lines 14-68) monitors buffer enters for frecency tracking and responds to DirChanged events automatically.

All high-level API functions in lua/fff/main.lua—including find_files() (lines 10-18) and live_grep() (lines 20-41)—are thin wrappers that marshal data between the Lua UI and Rust search engine. This separation allows the Rust backend in crates/fff-core/src/lib.rs to handle indexing, fuzzy scoring, and live grep operations with sub-millisecond latency while the Lua layer manages window rendering and keymaps.

Intelligent Ranking Systems

Frecency and Combo-Boost History

fff.nvim implements sophisticated scoring algorithms that learn from your usage patterns. The frecency system combines frequency and recency metrics to surface recently accessed files, while the combo-boost mechanism tracks successful query-to-file associations.

Configuration parameters in lua/fff/conf.lua (lines 48-49) control this behavior through min_combo_count and combo_boost_score_multiplier. When you repeatedly open the same file using identical search queries, the system boosts that file's score for future searches. This persistent history is stored in the Rust database and applied during the search_and_show flow in lua/fff/main.lua (lines 80-98).

Access these scores programmatically to build custom workflows:

local results = require('fff').search('init', 20)
for _, file in ipairs(results) do
  print(file.relative_path, '↦ frecency:', file.frecency_score)
end

Three-Mode Live Grep

Unlike standard pickers that offer only regex or fuzzy matching, fff.nvim supports three distinct grep modes switchable on-the-fly: plain text, regex, and fuzzy matching. The mode configuration resides in config.grep.modes (default defined at line 334 of lua/fff/conf.lua), with the UI rendering color-coded highlights (grep_plain_active, grep_regex_active, grep_fuzzy_active) to indicate the active state.

Cycle between modes during a live grep session using the configured keymap (default <S-Tab>):

require('fff').live_grep({
  grep = {
    modes = { 'fuzzy', 'plain' },
    max_file_size = 5 * 1024 * 1024,
  },
  query = vim.fn.expand('<cword>'),
})

Cross-Mode Suggestions

When a query yields zero results, fff.nvim automatically suggests alternative search strategies through cross-mode suggestions. If a file search returns nothing, the engine automatically executes a grep search and displays those results (and vice versa). This intelligent fallback is implemented in the search_and_show flow in lua/fff/main.lua (lines 5-22), eliminating dead-end searches without manual mode switching.

Git Status Integration

The picker provides first-class Git repository awareness through lua/fff/git_utils.lua. When enabled, the UI displays sign-column indicators showing file status (modified, added, untracked) and optionally applies color-coding to filenames based on their Git state.

Enable visual Git feedback in your configuration:

require('fff').setup({
  git = { status_text_color = true },
})

Highlight groups are defined in config.hl (lines 70-84 of lua/fff/conf.lua) and applied via git_utils.setup_highlights() during initialization (called from core.ensure_initialized() line 102).

MCP Support for AI Agents

fff.nvim includes built-in MCP (Model-Control-Protocol) support, allowing AI agents to invoke file searches without wasting context tokens on directory listings. This integration, referenced in lua/fff/download.lua, enables programmatic access to the search backend for automated tooling and agentic workflows.

Lazy Initialization Strategy

To preserve Neovim startup performance, fff.nvim employs deferred initialization via plugin/fff.lua (lines 14-23). By default, heavy indexing operations are scheduled until UIEnter or first use through an autocmd that calls core.ensure_initialized(). Disable this for immediate availability by setting lazy_sync = false in your configuration.

Configuration and Setup

Configure fff.nvim through the vim.g.fff global or direct setup call. The default configuration in lua/fff/conf.lua (lines 189-336) includes options for layout, keymaps, frecency, history, and Git integration:

require('fff').setup({
  base_path = vim.fn.getcwd(),
  lazy_sync = false,
  layout = {
    height = 0.85,
    width  = 0.85,
    preview_position = 'right',
    path_shorten_strategy = 'middle_number',
  },
  keymaps = {
    close = '<Esc>',
    select = '<CR>',
    cycle_grep_modes = '<S-Tab>',
  },
  frecency = { enabled = true },
  history  = { enabled = true, min_combo_count = 3 },
  git = { status_text_color = true },
})

Change the indexing directory dynamically to project roots:

require('fff').change_indexing_directory(
  require('fff.core').ensure_initialized().get_git_root()
)

Toggle debug score visualization inline:

:FFFDebug toggle

Or bind it to a key when the picker is active.

Summary

• fff.nvim pairs a Rust backend (fff.rust) with a Lua UI to deliver millisecond-latency fuzzy and grep searches in Neovim 0.10+.
• Frecency and combo-boost scoring in lua/fff/conf.lua learn from your query history to rank frequently-accessed files higher.
• Three-mode live grep supports plain, regex, and fuzzy matching with on-the-fly cycling via <S-Tab>.
• Cross-mode suggestions automatically fall back to alternative search types when queries return no results.
• Git integration provides sign-column markers and filename colorization via lua/fff/git_utils.lua.
• MCP support enables AI agents to leverage the search backend without token waste.
• Lazy initialization in plugin/fff.lua defers heavy indexing until UIEnter or first use.

Frequently Asked Questions

What makes fff.nvim different from Telescope or fzf-lua?

fff.nvim distinguishes itself through its Rust-powered backend that handles all indexing and scoring in native code, achieving sub-millisecond latency impossible with pure Lua implementations. It also offers unique features like combo-boost history scoring, three-mode grep switching, cross-mode suggestions, and built-in MCP support for AI agents that are not available in Telescope or fzf-lua.

How does the frecency scoring system work?

The frecency system tracks both how often and how recently you access files, storing this data in a Rust-managed database. When you repeatedly open the same file using identical search queries (meeting the min_combo_count threshold configured in lua/fff/conf.lua), the system applies a combo_boost_score_multiplier to elevate that file's ranking for future matching queries.

What is MCP support and how do I use it?

MCP (Model-Control-Protocol) support allows AI agents and automated tools to invoke fff.nvim's search capabilities programmatically without loading the UI. This prevents token waste from including directory listings in AI context windows. The functionality is handled through lua/fff/download.lua and the Rust binary interface, enabling headless search operations for agentic workflows.

Can I customize the window layout and keymaps?

Yes, fff.nvim offers extensive customization through the layout and keymaps configuration tables in lua/fff/conf.lua. You can adjust floating window dimensions, preview pane position (left/right), path shortening strategies, and bind custom keys for actions like close, select, cycle_grep_modes, and debug toggles. The UI layer in lua/fff/picker_ui.lua respects these settings via the config.layout and config.hl tables.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}