opensec-pi-fff is OpenSec's build of @ff-labs/pi-fff for Pi-Bolt, Pi compiled ahead of time on Bun. The tools, commands, modes, flags and config file are pi-fff's. What changes is how it reaches the native engine:

• Fast without the JIT. pi-fff calls FFF through bun:ffi, which needs the JIT, or else through @ff-labs/fff-node, which reads every field of every result with a separate native call. Pi-Bolt's default build runs without the JIT, so pi-fff takes the slow path there. This build makes the few native calls a search needs through ffi-rs and reads the results straight from native memory, which needs no JIT: searches run at about the speed of bun:ffi.
• Same speed with the JIT. On a build with the JIT (Pi-Bolt -jit, or Pi run by Bun) it uses bun:ffi, as pi-fff does.
• Starts faster. It ships as one prebuilt bundle that Bun loads natively, so Pi never transpiles it.

Install

pi-bolt install npm:opensec-pi-fff

• After installing, restart Pi-Bolt or run /reload.
• Update it with pi-bolt update --extensions, and remove it with pi-bolt remove npm:opensec-pi-fff.
• /fff-health shows how it calls the engine: bun:ffi, or ffi-rs (this build has no JIT).

Requirements

• Pi-Bolt 0.6 or later (Pi 1.0), or Pi run by Bun 1.3 or later.
• macOS (arm64, x64), Linux (x64, arm64; glibc or musl), or Windows (x64, arm64).
• This build runs on Bun only. For Pi on Node, use @ff-labs/pi-fff.
• Install one of the two, not both: they register the same tools, commands and flags.

Speed

Milliseconds per call inside Pi-Bolt 0.8.1 on an Apple M5, median of 3 runs. pi-fff on the build without the JIT uses fff-node; with the JIT both use bun:ffi.

| Search | Repository | pi-fff, no JIT | opensec-pi-fff, no JIT | either, with JIT | |---|---|---:|---:|---:| | fileSearch, 50 results | Bun (19,869 files) | 4.14 | 2.63 | 2.62 | | glob **/*.ts, 200 results | Bun | 7.29 | 1.67 | 1.48 | | grep regex, 100 matches | Bun | 5.22 | 2.11 | 1.97 | | grep literal, 100 matches | Pi-Bolt (2,169 files) | 22.80 | 1.82 | 1.06 | | glob **/*.ts, 200 results | Pi-Bolt | 6.09 | 0.57 | 0.35 |

A first start after installing or upgrading (no transform cache) took 147 ms instead of 291 ms for the same prompt.

Tools and commands

| Tool / command | What it does | |---|---| | fffind | Fuzzy file search, ranked by frecency and git status. Globs too. | | ffgrep | Content search: smart case, plain text by default, regex or fuzzy on request, cursor pagination. | | fff-multi-grep | Searches for any of several literal patterns at once. Off unless PI_FFF_MULTIGREP=1, as in pi-fff 0.11.0. | | @ autocomplete | FFF-backed file and directory suggestions in the editor. | | /fff-health | Index, git, frecency and history status, and how the engine is called. | | /fff-rescan | Rescans the files. | | /fff-mode <mode> | tools-and-ui (default), tools-only, or override (replaces the built-in find and grep). |

Configuration

Optional, and the same as pi-fff's: pi-fff.json in Pi's agent directory, the --fff-* flags and the FFF_* / PI_FFF_MODE environment variables. See pi-fff's README for every option, and for where the frecency and query-history databases live. Switching between the two packages keeps your settings and search history.

This build adds two options:

| Option | Flag / env | Effect | |---|---|---| | profile | --fff-profile, PI_FFF_PROFILE | default or audit. In audit, ffgrep searches literal text, case-sensitively, never falls back to fuzzy matches, and starts its output with the mode it used ([mode: literal, case-sensitive]). Its regex and caseSensitive parameters still override this per call. Frecency persistence is off unless you turn it on. | | disableFrecency | --fff-disable-frecency, FFF_DISABLE_FRECENCY | Do not open the frecency and history databases, so ranking does not depend on earlier sessions. Defaults to on in audit, off otherwise. |

Search results: what to rely on

• ffgrep waits for the content index to finish warming up before its first search. If it is still not ready after 30 seconds, the result says so.
• A directory in path (net/, net/core) means that directory at the repo root, not any directory with that name. Excludes still match the name anywhere (test/ excludes every test directory).
• A regex that can cross a line break ([^,]*, \s, ...) can make the engine report a line that does not match on its own. Those matches are dropped, and the result says how many.
• The result names any file that reached the cap of 200 matches per file. When nothing matches (or in audit), it also says how many indexed files were not searched (binary, or larger than 10 MB), and warns when the directory is not a git work tree.
• Output is ranked and capped, so it is not proof that something is absent. For an exhaustive sweep, use rg.
• The engine does not index hidden files or (in a git work tree) ignored files, and has no option to include them. followSymlinks is accepted but has no effect in engine 0.11.

How this build is packaged

• dist-bun/index.js is a small ESM entry that Pi loads.
• dist-bun/core.cjs is the extension and the FFF SDK (pi-fff 0.11.0 and fff-bun 0.11.0), as readable CommonJS that Bun loads natively, fresh on every load.
• The native engine comes from the @ff-labs/fff-bin-* package for your platform, and ffi-rs from its own platform package. Both are prebuilt; nothing is compiled or downloaded at install time.

Changes from upstream

Based on @ff-labs/pi-fff 0.11.0 and @ff-labs/fff-bun 0.11.0.

• The SDK is bundled, and its library loader falls back to ffi-rs when bun:ffi cannot load the library (no JIT). Everything else in the SDK, including how results are decoded, is fff-bun's.
• @ff-labs/fff-node is not used.
• The native library is loaded only from the @ff-labs/fff-bin-* package installed with this one. fff-bun also looks in a development workspace two directories above the package.
• watch() (not used by the extension) needs the JIT; without it, it returns an error instead of a subscription.
• /fff-health shows how the engine is called, the profile, whether frecency persistence is on, and whether the content index is ready.
• ffgrep waits for the content index before its first search, has an audit profile and a regex parameter, drops regex matches that only match across a line break, and reports per-file caps and unsearched files.
• A directory path is anchored at the repo root (net/ no longer matches drivers/net/).
• fffind pages no longer overlap: the engine's pageIndex is an item offset, and the extension passed a page number.
• Sessions in one process (a parent and its in-process subagents) share one index per directory instead of building their own; the last session to shut down frees it.
• disableFrecency option.

License

MIT, like pi-fff and fff: see LICENSE and NOTICE. FFF is by Dmitriy Kovalenko.