dmtrKovalenko/fff

FFF is a high-performance, cross-platform file search and content grep engine built in Rust, designed for integration into developer tooling and AI agents. It provides fuzzy file discovery, live content searching, and filesystem watching capabilities through native bindings for Neovim, Python, Node.js, and Bun, as well as a Model Context Protocol (MCP) server for AI integration. The system emphasizes speed and reliability via SIMD-accelerated search, bigram-based prefiltering, and robust background indexing with Git status tracking.

Users can now install the fff-mcp tool (a fast file search toolkit for AI agents) via Homebrew. The new Formula/fff-mcp.rb file provides pre-built binaries for macOS (Apple Silicon and Intel) and Linux (ARM and Intel), automatically fetching the v0.11.0 release assets from the upstream GitHub repository.

Formula · high confidence

New command-line tools have been added to the \fff-nvim\ crate to help developers and power users evaluate performance and stability. \bench\_grep\_query\ and \grep\_profiler\ benchmark the grep pipeline, including live-typing latency simulations. \grep\_vs\_rg\ compares fff's in-process search speed against ripgrep (shelling out). \bench\_search\_only\ and \search\_profiler\ profile fuzzy file search performance. \bench\_lmdb\_parallel\ measures database contention under concurrent access. \fuzzy\_grep\_test\ validates match quality for fuzzy grep queries. Finally, \jemalloc\_profile\, \test\_memory\_leak\, \rescan\_probe\, and \test\_watcher\ provide detailed insights into memory usage, leak detection, and file-watcher behavior.

crates/fff-nvim/src/bin · high confidence

The grep module has been restructured into dedicated sub-modules (grep, fuzzy\_grep, regex, multi\_pattern, prefilter, sink, classify) to support new search capabilities. Users can now perform fuzzy searches (allowing typos and gaps) via the new \Fuzzy\ mode, which uses the neo\_frizbee library for SIMD-accelerated approximate matching. Multiline regex searches are now supported, allowing patterns to span across line breaks. Additionally, when the \definitions\ feature is enabled, grep results can be annotated to identify code definitions (structs, functions, classes) versus imports, aiding AI and MCP consumers. The search engine also includes performance optimizations such as Aho-Corasick for multi-pattern literal searches, time budgets to prevent UI freezes, and improved prefiltering with filepath constraint fallbacks.

crates/fff-core/src/grep · high confidence

The plugin now ships with official Neovim documentation (fff.nvim.txt), providing users with installation instructions for lazy.nvim and vim.pack, a reference for the public Lua API (including file\_search and content\_search), and configuration details. This replaces the previous lack of generated docs and ensures users have a single source of truth for setup and usage.

doc · high confidence

The \@ff-labs/fff-bun\ package is now available, providing a native Bun implementation of the fff file finder. It includes a new binary resolution system that automatically detects the platform (including Android arm64/Termux and Linux musl/glibc) and loads the corresponding prebuilt native library from platform-specific npm packages or local dev builds. The package exposes the same public API as the Node.js version, including file search, grep, and file watching capabilities, ensuring compatibility for Bun users while leveraging Bun's FFI for performance.

packages/fff-bun/src · high confidence

This change adds the initial Lua interface for the fff-nvim plugin, exposing core file-search capabilities to Neovim users. It provides functions to initialize the file picker and databases, and exposes search results (files, directories, grep matches) as Lua tables with detailed scoring and match-range information. Additionally, it introduces a new hex-dump viewer for binary files, allowing users to preview non-text files with colorized output and paging support. The module also includes path-shortening strategies for cleaner UI display and configurable user options for filename constraints and grep parsing.

crates/fff-nvim/src · high confidence

The \@ff-labs/fff-node\ package now provides a Node.js interface to the fff file finder, exposing the \FileFinder\ class for fuzzy search, grep, and file watching. The package includes a postinstall script and CLI utilities that automatically resolve and download the required native Rust binary (libfff\_c) from GitHub or platform-specific npm packages, ensuring the library is available at runtime.

packages/fff-node/src · high confidence

This change adds a new Python module (\fff-python\) that exposes the core file-finding, grep, and file-watching capabilities of the fff engine to Python applications via PyO3 bindings. Users can now instantiate a \FileFinder\ to perform fuzzy searches, grep queries, and directory scans, receiving structured results including file items, directory items, and grep matches with associated scores and metadata. The bindings also support file system watching through a \WatchSubscription\ context manager, allowing Python code to react to file changes. This provides a native, high-performance interface for integrating fff's search and indexing features into Python tooling.

crates/fff-python · high confidence

Adds a new \fff-search\ package providing Python bindings for the FFF file finder, built with PyO3 and Maturin. Users can install the package via pip and use the \FileFinder\ class to index directories, perform fuzzy and glob searches, and grep for content. The bindings support both synchronous and asynchronous workflows and include a file-watching feature that notifies subscribers of filesystem changes, including file renames.

packages/fff-python · high confidence

Users can now interact with FFF from Python via a new package that exposes file searching, grep, and file-watching capabilities. The bindings provide an async-friendly \FileFinder\ class with a non-blocking \wait\_for\_scan\ method, along with type stubs for static analysis. This allows Python applications to perform fast file discovery and content searches without blocking the event loop.

packages/fff-python/src · high confidence

Adds the \@ff-labs/fff-bun\ package, providing a high-performance fuzzy file finder for Bun applications backed by a native Rust library. The SDK supports file, content (grep), and directory searches with typo resistance, along with real-time file watching and git status integration. It includes prebuilt binaries for macOS, Linux, and Windows, and allows embedding the native library into standalone executables via \bun build --compile\.

packages/fff-bun · high confidence

This change introduces the \fff-core\ crate, establishing the foundational components for the file finder's search engine. It adds a new \FilePicker\ for background indexing and real-time filesystem watching, alongside a \FrecencyTracker\ for intelligent result ranking. The update includes platform-specific optimizations, such as tuning thread pools for macOS performance cores and configuring LMDB for database stability. It also adds Git integration for status caching and recency scoring, a live grep search module, and robust error handling and logging infrastructure to improve reliability and crash diagnostics.

crates/fff-core/src · high confidence

The new \fff-grep\ crate provides a simplified, line-oriented grep engine for \fff.nvim\ that operates directly on byte slices. It supports both single-line and multi-line search modes, allows configuration of line terminators and line number reporting, and uses a push-based \Sink\ trait to deliver match results (including byte offsets and line numbers) to consumers.

crates/fff-grep · high confidence

This change introduces the \fff-mcp\ server, a Model Context Protocol (MCP) interface for the FFF file finder, enabling AI code assistants to search file contents and explore project structure. The server includes a \ProbeTolerantTransport\ to prevent crashes from pre-initialization requests, a \CursorStore\ for paginated grep results, and a \ParentWatcher\ to ensure the server exits when its parent process dies. It also provides a \healthcheck\ command to validate configuration paths and an automatic update checker that compares the current version against the latest stable release.

crates/fff-mcp/src · high confidence

Adds the \pi-fff\ extension, which overrides the built-in \find\ and \grep\ tools with FFF-backed versions (\fffind\, \ffgrep\) and adds FFF-powered @-mention autocomplete. The extension introduces a new configuration file (\pi-fff.json\) to control scanning behavior, including options to enable or disable home directory and filesystem root scanning, follow symlinks, and mute home-scan warnings. It implements an auxiliary finder pool to handle searches outside the current workspace (e.g., \\~\ or \../other-project\) while deduplicating concurrent scans to improve performance. The extension also supports a global config file, persists FFF mode across reloads, and includes a fallback mechanism to load the FFF SDK from either Bun or Node.js environments.

packages/pi-fff/src · high confidence

The plugin now ships with prebuilt Rust binaries (libfff\_nvim) that are automatically downloaded and validated, removing the need for users to compile from source. A new configuration module (conf.lua) defines a structured schema for layout, preview, keymaps, and frecency settings, including migration logic for deprecated options like top-level width/height. The core module (core.lua) adds robust directory change handling with path canonicalization to prevent unnecessary re-indexing, while the download module ensures atomic binary updates with integrity checks. Additionally, the highlights module now supports dynamic git sign border blending with the cursor line, and the layout module implements flexible, responsive window positioning with configurable border presets.

lua/fff · high confidence

The plugin now supports downloading prebuilt binaries instead of requiring a local Rust build. This change adds utility modules to detect the current platform (including specific support for Android/Termux and musl vs glibc Linux) and to resolve the correct version tag for download, preferring per-commit SHA tags for nightly builds to ensure stability. Users benefit from faster installation times and broader platform compatibility without needing to compile the tool from source.

lua/fff/utils · high confidence

The fff-core crate now supports a \zlob\ feature that leverages a Zig-compiled C library to provide faster glob matching and overall performance improvements. This feature is optional; if Zig is detected on the system but the feature is not explicitly enabled, a build warning is emitted to suggest enabling it for better performance. On Windows MSVC builds, the build script automatically links the necessary C runtime libraries when the \zlob\ feature is active to resolve symbol dependencies.

crates/fff-core · high confidence

The index now uses a bigram-based content prefilter to significantly speed up search queries. This new subsystem (bigram\_filter, bigram\_query, candidates) builds an inverted index of character pairs from file contents, allowing the search engine to quickly narrow down candidate files before performing expensive full-text matching. The implementation includes optimized bitset operations, fuzzy matching support via evenly-spaced probe bigrams, and regex-to-bigram query translation, resulting in reduced memory usage and faster query response times.

crates/fff-core/src/index · high confidence

The examples directory now includes four new Bun-based scripts that demonstrate the library's capabilities. \search.ts\ provides an interactive fuzzy file and directory finder with detailed scoring breakdowns and git status indicators. \grep.ts\ offers a live content search tool supporting plain, regex, and fuzzy modes with match highlighting. \watch.ts\ demonstrates the file watcher API, reporting file creation, modification, and removal events. Additionally, \glob-bench.ts\ allows users to benchmark the library's globbing performance against Bun's native \Bun.Glob\ and the npm \glob\ package.

packages/fff-bun/examples · high confidence

This change introduces several new scripts to support development and release workflows. A new benchmark suite (benchmark-claude.sh and analyze-results.py) allows comparing the performance of the fff MCP against Claude Code's native tools across ten search concepts, tracking cost, turns, and wall time. Release automation is improved with a new release.sh script that handles version bumping for Rust, Python, and npm packages, and a set-npm-version.mjs script to manage workspace dependencies. Additionally, a diagnose\_lockmdb.py script is added to help debug LMDB locking issues by inspecting mutex states and process mappings, and a determine-version.lua script exposes version metadata for CI integration.

scripts · high confidence

The \fff-c\ crate now provides a stable C interface for external consumers (such as Python, Node.js, or Bun), allowing them to interact with the file finder without relying on JSON serialization. This includes versioned \FffCreateOptions\ and \FffWatchOptions\ structs to ensure ABI stability as new fields are added, and a set of accessor functions (e.g., \fff\_file\_item\_get\_relative\_path\) to safely read struct fields without hardcoding byte offsets. The API exposes core capabilities like file searching, live grep, and filesystem watching through a single opaque instance handle, with all result types defined as \\#\[repr(C)\]\ structs for direct memory access.

crates/fff-c · high confidence

The \test\_watcher.rs\ binary in \src/bin\ has been deleted. This file previously served as a standalone executable for live file monitoring, displaying file additions/removals, git status statistics, and performing periodic fuzzy search tests. Its removal eliminates this specific diagnostic tool from the build.

src/bin · high confidence

The \packages/shared\ area now provides a single, self-contained source of truth for the public API types and interfaces used by both the Node and Bun implementations of the fff file finder. This change introduces a unified \fff-api.ts\ file that defines core structures such as \InitOptions\, \SearchOptions\, \FileItem\, and \Score\, ensuring consistent behavior across platforms. Users benefit from a standardized interface for initialization (including options like \disableWatch\ and \followSymlinks\) and search operations, with the API automatically synchronized to the respective package implementations.

packages/shared · high confidence

The monolithic picker\_ui.lua implementation has been split into a set of focused submodules (picker\_ui\_state, ui\_creator, search\_manager, renderer, preview\_manager, navigation, layout\_manager, file\_renderer, grep\_renderer, combo\_renderer, list\_renderer, and utils) to improve maintainability and separation of concerns. The new architecture uses a coordinator pattern where picker\_ui.lua wires these modules together, sharing state via a single table reference (picker\_ui\_state) and allowing cross-module coordination through parent module references.

_lua/fff/picker\ui · high confidence

The file picker now shows a detailed file information panel (including size, type, git status, and frecency scores) with custom syntax highlighting, replacing the previous minimal preview. Image previews have been refactored to load metadata asynchronously and reserve buffer space more efficiently, while the icon provider module has been simplified to remove hardcoded directory mappings and fallback colors, relying entirely on the configured icon provider (nvim-web-devicons or mini.icons). The search API now supports pagination and location data, and the setup process has been streamlined to remove forced configuration defaults.

_lua/fff/file\picker · high confidence

The database layer now shares a single LMDB environment per path within a process and raises the maximum reader count to prevent 'MDB\_READERS\_FULL' errors and stale reader issues, ensuring more stable file tracking. Additionally, case-insensitive string searches are significantly faster on supported hardware by using new SIMD-accelerated implementations for AVX2 (x86\_64) and NEON (aarch64).

crates/fff-core/src/dbs · high confidence

The file watcher has been refactored into a background service that runs in a dedicated thread, improving responsiveness and reducing unnecessary rescans. The new implementation correctly handles empty directories and file renames, ensuring that file system changes are processed incrementally without triggering full index rebuilds. It also optimizes performance on large directories by reducing the frequency of rescans and properly managing platform-specific file system event limits on macOS and Windows.

crates/fff-core/src/watcher · high confidence

The plugin now defers its indexing process until after the UI enters, preventing startup blocking and improving perceived performance. Additionally, several new user commands are introduced to enhance workflow: FFFResume restores the last picker state, FFFFind allows searching by directory or query, FFFScan and FFFRefreshGit enable manual indexing and Git status updates, FFFClearCache manages internal caches, and FFFDebug/FFFOpenLog provide debugging and logging capabilities.

plugin · high confidence

The project now requires the Rust stable toolchain instead of nightly, simplifying the build environment and removing the need for nightly-specific components. Users no longer need to manage a nightly Rust installation to build or use the plugin.

(repo-wide) · high confidence

The file search query parser has been replaced with a new system that supports structured constraints (such as file extensions, globs, path segments, file types, and git status) alongside fuzzy text matching. This change introduces distinct parsing modes: the default file picker mode treats partial filenames as fuzzy text to avoid accidental filtering, while the grep mode enables filename constraints for scoping and restricts glob detection to path-oriented patterns (preventing code characters like \?\ or \\[\ from being misinterpreted as wildcards). The parser also adds support for location suffixes (e.g., \file:12\) and AI-mode grep, which automatically scopes searches to matching files based on filename patterns.

crates/fff-query-parser/src · high confidence

The Rust backend is now loaded from prebuilt binaries rather than requiring a local \cargo build\. The \init.lua\ script now attempts to load the library from a downloaded binary path first, falling back to the build directory, and correctly handles Windows path separators and the \CARGO\_TARGET\_DIR\ environment variable. This change also removes the internal Rust modules (\error.rs\, \file\_key.rs\, \file\_picker.rs\, \frecency.rs\, \git.rs\, \lib.rs\, \path\_utils.rs\, \score.rs\, \tracing.rs\, \types.rs\) as the logic has been refactored or moved elsewhere.

lua/fff/rust · high confidence

Add benchmark suite for search and indexing performance; Added Criterion-based benchmarks for search, grep, and query tracking; Added benchmark suite for query parser performance; Added comprehensive test suite for fff-node; Added comprehensive test suite for fff.nvim core and UI; Added comprehensive tests for file picker stability and indexing correctness; Added integration tests for FileFinder lifecycle, platform detection, and file watching; Added integration tests for MCP parent-process liveness behavior; Added screenshot tests for picker UI layout and file info panel; Added tests for Python bindings and file watcher functionality; Added tests for pi-fff search and configuration logic.

This release introduces version 0.11.0 of the core file finder, featuring new official SDKs for Python (fff-python), C (fff-c), and a Model Context Protocol server (fff-mcp) for AI integration. It adds prebuilt native binaries for Android ARM64 (Termux) and expands platform support across macOS, Linux, and Windows. The Rust core is updated to edition 2024, and the dependency \git2\ is bumped to 0.21.0 to address security advisories RUSTSEC-2026-0183/0184.

(dependencies) · high confidence

An empty .gitkeep file was added to the crates/fff-mcp/server directory to ensure the directory is tracked in version control. This change has no functional impact on the product.

crates/fff-mcp/server · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 64 → 66 (+1.2)
• Rubric changed (rubric-2026.09.8 → rubric-2026.09.17) — scores are not directly comparable.

• Code Health 58 → 58 (-0.1)
• Architecture 100 → 98 (-2.0)
• Maturity 68 → 66 (-2.4)
• Readiness 73 → 71 (-1.5)
• Security 63 → 74 (+11.0)
• Performance 100 (new)

• BigramQuery::evaluate_cow (cognitive 23) (crates/fff-core/src/index/bigram_query.rs)
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (10 lines × 2) (crates/fff-core/src/score.rs)
• Duplicated block (12 lines × 2) (crates/fff-core/src/index/bigram_query.rs)
• Duplicated block (34 lines × 2) (crates/fff-core/src/score.rs)
• Duplicated block (5 lines × 2) (crates/fff-core/src/simd_path.rs)
• Duplicated block (6 lines × 2) (crates/fff-core/src/score.rs)
• Duplicated block (6 lines × 2) (crates/fff-core/src/score.rs)
• Duplicated block (7 lines × 2) (crates/fff-core/src/score.rs)
• Duplicated block (8 lines × 2) (crates/fff-core/src/index/bigram_filter.rs)
• Duplicated block (8 lines × 2) (crates/fff-core/src/index/bigram_filter.rs)
• FunctionTooLong: fff_search::score::match_and_score_in_arena (crates/fff-core/src/score.rs)
• Hotspot: crates/fff-core/src/dbs/env_pool.rs (crates/fff-core/src/dbs/env_pool.rs)
• Hotspot: crates/fff-core/src/file_picker.rs (crates/fff-core/src/file_picker.rs)
• Hotspot: crates/fff-core/src/index/bigram_query.rs (crates/fff-core/src/index/bigram_query.rs)
• Hotspot: crates/fff-mcp/src/server.rs (crates/fff-mcp/src/server.rs)
• Hotspot: crates/fff-query-parser/src/parser.rs (crates/fff-query-parser/src/parser.rs)
• Hotspot: packages/fff-bun/src/finder.ts (packages/fff-bun/src/finder.ts)
• Hotspot: packages/fff-node/src/finder.ts (packages/fff-node/src/finder.ts)
• …and 7 more

• BigramIndexBuilder::compress (cyclomatic 19) (crates/fff-core/src/index/bigram_filter.rs)
• Dependency hygiene PARTLY measured — Cargo dependencies read, dependency currency not (crates.io unreachable)
• Duplicate function signatures in the same module. The second signature uses an underscore-prefixed parameter _bytes, which in Rust usually indicates an unused variable, but having two functions with the same name and signature in the same scope is a compilation error or indicates a copy-paste error in the API surface provided.
• Duplicated block (10 lines × 2) (crates/fff-core/src/score.rs)
• Duplicated block (18 lines × 2) (crates/fff-core/src/score.rs)
• Duplicated block (6 lines × 2) (crates/fff-core/src/index/bigram_filter.rs)
• Duplicated block (7 lines × 2) (crates/fff-core/src/index/bigram_filter.rs)
• Duplicated block (9 lines × 2) (crates/fff-core/src/watcher/background_watcher.rs)
• Duplicated block (9–11 lines × 2) (crates/fff-core/src/dbs/frecency.rs)
• FunctionTooLong: fff_search::score::match_and_score_in_arena_inner (crates/fff-core/src/score.rs)
• High CVE: [GHSA redacted] (Cargo.lock)
• Hotspot: crates/fff-core/src/index/bigram_filter.rs (crates/fff-core/src/index/bigram_filter.rs)
• Hotspot: crates/fff-nvim/src/bin/grep_profiler.rs (crates/fff-nvim/src/bin/grep_profiler.rs)
• Inconsistent method naming for search variants. fuzzy_search is the default, but fuzzy_search_directories and fuzzy_search_mixed are explicit. However, fuzzy_search takes a query_tracker while fuzzy_search_directories does not. The naming doesn't clearly indicate that fuzzy_search is 'files only' vs 'mixed'.
• Inconsistent return type for path lookup. One returns the item directly (implying it always exists or panics/returns default), while the other returns an Option. This creates confusion about whether the item is guaranteed to exist.
• Medium CVE: [GHSA redacted] (packages/bun.lock)
• Members sharing a duplicated core (4 members, 50+ identical tokens) (crates/fff-c/src/lib.rs)
• Members sharing a duplicated core (4 members, 50+ identical tokens) (crates/fff-c/src/lib.rs)
• Members sharing a duplicated core (4 members, 50+ identical tokens) (crates/fff-nvim/src/bin/bench_grep_query.rs)
• Off the main sequence: @ff-labs/fff-bun
• …and 12 more

• 25 commits — 15 feature/other, 10 fixes

• crates/fff-core — 9 commits
• packages/pi-fff — 5 commits
• (root) — 3 commits
• doc/fff.nvim.txt — 3 commits
• lua/fff — 2 commits
• packages/fff-bun — 2 commits
• packages/fff-python — 1 commit

• fix: fix(fff-mcp): apply --max-cached-files as a cap, not a repo size (#847) (#848)
• fix: fix(nvim): keep grep match bg on preview target line (#886)
• fix: fix(pi-fff): drop stale mode tool names on reload (#855) (#856)
• fix: fix(pi-fff): fall back to fff-node when fff-bun cannot be imported (#779)
• fix: fix(pi-fff): preserve FFF tool renderers across reload (#854)
• fix: fix(pi-fff): skip the picker instead of erroring when cwd scanning is opted out (#857) (#858)
• fix: fix(sdk): decode FffGrepMatch and FffScore with the real C layout in fff-node and fff-bun (#891)
• fix: fix(windows): rename events paths arrive correctly (#881)
• fix: fix: Do not start fallback grep if index is not ready (#880)
• fix: fix: refuse home dir when base path has a trailing separator (#890)
• change: chore: add RapidProxy as a sponsor (#877)
• change: chore: bump fff-mcp release artifacts to v0.11.0
• change: chore: regenerate Neovim vimdoc (#871)
• change: chore: regenerate Neovim vimdoc (#876)
• change: chore: regenerate Neovim vimdoc (#882)
• change: chore: release 0.11.0
• change: feat(c): support cargo-c and install pkg-config file (#879)
• change: feat(pi-fff): add compact clickable rendering for search tools (#852)
• change: feat(sdk)!: add case_mode: smart, sensitive, insensitive option (#609)
• change: feat: Catch renames during watcher (#767)
• …and 5 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

dmtrKovalenko/fff was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.