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

> Discover fff.nvim's unique features. This Rust-powered fuzzy file picker for Neovim offers lightning-fast searches, frecency ranking, live grep, and AI integration.

- Repository: [Dmitriy Kovalenko/fff.nvim](https://github.com/dmtrKovalenko/fff.nvim)
- Tags: deep-dive
- Published: 2026-04-04

---

**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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/main.lua) (lines 80-98).

Access these scores programmatically to build custom workflows:

```lua
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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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>`):

```lua
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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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:

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

```

Highlight groups are defined in `config.hl` (lines 70-84 of [`lua/fff/conf.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/conf.lua) (lines 189-336) includes options for layout, keymaps, frecency, history, and Git integration:

```lua
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:

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

```

Toggle debug score visualization inline:

```vim
: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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/git_utils.lua).
- **MCP support** enables AI agents to leverage the search backend without token waste.
- **Lazy initialization** in [`plugin/fff.lua`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/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`](https://github.com/dmtrKovalenko/fff.nvim/blob/main/lua/fff/picker_ui.lua) respects these settings via the `config.layout` and `config.hl` tables.