pi-fzf-files - Pi extension

Pure TypeScript replacement for Pi's default @ file-reference autocomplete. It builds an in-memory file index on session start/restart, refreshes it asynchronously when you use @, and searches it with fzf-style extended query syntax—no fzf, fd, sqlite package, or other runtime dependency required.

Features

• Replaces @... file suggestions through ctx.ui.addAutocompleteProvider().
• Does not delegate on @ misses, so Pi's default fd-backed finder does not appear for file references.
• Starts indexing asynchronously on every session start/restart.
• Starts a background reindex when you enter an @ file query, unless one is already running.
• Searches a cached in-memory index instead of walking the filesystem per keystroke.
• Rebuilds into a temporary index and atomically swaps it in, so background reindexing does not clear existing suggestions.
• Follows symlinked files and directories while avoiding recursive symlink cycles.
• Skips heavy directories such as .git, node_modules, dist, build, .next, coverage, target, and virtualenv/cache folders.
• Supports fzf extended syntax:

Input	Match type	Description
cmp	fuzzy-match	Items that match cmp, such as ComponentMap or createMessageParser.
'useState	exact-match (quoted)	Items that include useState, such as useStateReducer.
'auth'	exact-boundary-match (quoted both ends)	Items that include auth at word boundaries, such as auth-token or auth.service.
^use	prefix-exact-match	Items that start with use, such as useUserSession.
Controller$	suffix-exact-match	Items that end with Controller, such as UserController.
!deprecated	inverse-exact-match	Items that do not include deprecated.
!^legacy	inverse-prefix-exact-match	Items that do not start with legacy.
!Spec$	inverse-suffix-exact-match	Items that do not end with Spec.
sb controller	multiple-terms (AND)	Items that match both sb AND controller, such as SidebarController.
sb | controller	OR-match	Items that match either sb OR controller, such as Sidebar or UserController.
'controller auth | session	exact AND OR-match	Items containing controller exactly, and matching either auth or session fuzzy, such as AuthController.ts or session_controller.rb.
'auth | 'session	multiple exact (OR)	Items containing either auth exactly or session exactly, such as auth.ts or session.py (excluding author.ts).
'src 'test	multiple exact (AND)	Items containing both src exactly and test exactly, such as src/app.test.ts.
foo|bar	literal pipe	Matches a literal pipe inside a token, such as docs/foo|bar.md (no spaces around |).
Foo	smart-case match	Uppercase characters make the term case-sensitive (e.g., Foo only matches items containing Foo, but foo matches both foo and Foo).

Spaces can be escaped inside a token with \.

Frecency

Submitted prompts are scanned for @path and @"path with spaces" references. Referenced files are recorded in a project-scoped JSON hashmap under:

~/.pi/agent/fzf-files/frecency-v1/<cwd-hash>.json

Ranking uses match quality first. Frecency is a tie-breaker, so frequently/recently referenced files move up when the textual match is otherwise equal.

SQLite would only help once the index itself lives on disk or queries need cross-project aggregation. For this extension the hot path is an in-memory top-K scan over cached paths, while frecency lookups are O(1) map reads. The JSON store keeps runtime installs dependency-free and portable across Pi's supported Node runtimes.

Install

From npm:

pi install npm:pi-fzf-files

Try it without installing permanently:

pi -e npm:pi-fzf-files

From this repository:

pi -e ./pi-fzf-files
# or
pi install ./pi-fzf-files

If you also want Pi startup to avoid provisioning the built-in fd helper entirely, run Pi with PI_OFFLINE=1 or add a Pi core setting when available. This extension itself never invokes fd.

Commands

/fzf-files help
/fzf-files stats
/fzf-files reindex
/fzf-files clear-frecency

/fzf-files help opens a formatted Markdown help view with separate command and syntax-example tables /fzf-files syntax opens a syntax examples table

Development

bun test
npm run typecheck