telescope-frecency.nvim: a file picker that learns what you open

Recency weighted by frequency, borrowed from Firefox

telescope-frecency.nvim is a telescope.nvim extension that offers intelligent prioritization when selecting files from your editing history. The mechanism is Mozilla's frecency algorithm, the one used in Firefox's address bar, and the effect is that files edited frecently are given higher precedence in the list index.

Frecency is a score rather than a sort key. A file you opened a moment ago counts for more than one you opened yesterday, a file you open many times counts for more than one you opened once, and the combination of the two is what the algorithm computes. As the extension learns your editing habits over time, the sorting of the list is dynamically altered to prioritize the files you are likely to need.

The learning is local. The scores live in a database file in your Neovim data directory, and the ranking is applied when the finder opens. There is no server, no account and no telemetry in the design, which is consistent with the plugin being a Neovim extension.

One small detail that tells you about the project: the screenshot in the README shows scores next to the entries, and the caption says those are for demonstration purposes and disabled by default. The point of the plugin is that the ordering changes, not that you read numbers.

The implementation is Lua, the licence is MIT, and the plugin targets Neovim with telescope.nvim as a hard dependency.

The cold start problem, and workspace tags as the answer

The README asks a fair question: what about files that are neither frequent nor recent? Frecency naturally works best for indexed files that have been given a reasonably high score, so new projects, and rarely used files with generic names, either do not get listed at all or get buried under results with a higher score.

That is the failure mode of any ranking system, and it bites hardest in the first week of a new project, which is exactly when you most want a good file picker.

The answer in this plugin is workspace filters. You define filter tags that map to a directory or a collection of directories, and you apply a filter by entering the tag in the query, in the form :workspace_tag: with the surrounding colons. Name completion works by pressing Tab after the first colon character, in the case where enable_prompt_mappings is true.

The semantics of an applied filter are worth spelling out, because they are not just a view filter. Results are reduced to entries whose path is a descendant of the workspace directories. The indexed results are optionally augmented with a listing of all files found in a recursive search of the workspace directories.

So a workspace tag does two things at once: it narrows the list, and it can pull in files that frecency has never seen.

Non-indexed files arrive at zero and leave with a score

The scoring behaviour for files that are not in the index is specific and worth understanding.

Non-indexed files are given a score of zero, and they appear below the frecent entries. When a non-indexed file is opened, it gains a score value and is available in future frecent search results.

That is a small design decision with a large effect on how the plugin feels. A file you have never touched is not hidden, it is demoted. It shows up when you ask for it with a workspace filter or when the rest of the list is empty of better matches, and the moment you open it, it enters the ranking for good.

Compare that with the alternative, where unseen files are simply absent, and you get a picker that is fast and accurate for your habits and useless in the first hour of a new project. The demote-then-promote behaviour is what makes frecency usable as a general purpose file finder rather than a shortcut manager.

The recursive search that backs the augmented listing is where an external tool earns its place. The README notes that fd or ripgrep will be used to list up workspace files, and that they are extremely faster than the native Lua logic, and that if you do not have them the plugin falls back to Lua code automatically. The optional dependency is therefore a performance choice rather than a functional one.

Two tags exist without configuration: CWD and LSP

Two workspace tags are available out of the box, and both are derived from the state of your editor rather than from configuration.

The first is CWD, a default pre-defined workspace tag, so you can filter entries into the ones under the current working directory. That is the quick way to say this finder is about the project I am standing in, rather than about everything I have ever opened.

The second is LSP, and it is the more interesting one. If the active buffer, prior to the finder being launched, is attached to an LSP server, an automatic LSP tag is available, and it maps to the workspace directories provided by the language server.

That is a genuinely clever piece of plumbing, because it means the tag follows the code you are looking at rather than the shell you happened to be in. Open a buffer from a language server with a multi-root workspace, launch the finder, and the filter is already scoped to the roots that server told the editor about. No configuration, and it stays correct as you move between projects.

Together with user defined tags, you get three ways to scope a search: a static directory you configured, the current working directory, and the workspace of the language server you are currently attached to.

The Neovim version matrix is unusually spread out

The requirements section is where a plugin like this usually gets complicated, and this one is explicit about it.

The main requirement is Neovim v0.11.7 or higher, which the README notes matches telescope.nvim. There are then two compatibility carve-outs. Use the ^0.9.0 tag for Neovim 0.9.x, and for Neovim 0.10.x, lock to a release before 2.0.0.

The versioning notice explains why the carve-outs exist. A tagged release 1.0.0 is published and it drops the support for Neovim 0.9.x, so anyone still on 0.9.x is pointed at the ^0.9.0 tag for their plugin manager.

The optional dependencies are listed with the same care. nvim-web-devicons is optional, and fd or ripgrep is optional, with the note about the Lua fallback described above.

For a plugin manager, the practical effect is that the version constraint is not a single line but a decision. If your Neovim is current, you install the latest. If it is 0.10.x, you pin below 2.0.0. If it is 0.9.x, you pin the ^0.9.0 tag and you are on the v1 line permanently.

The installation snippet for Lazy.nvim is short, and the extension is loaded the standard telescope way.

{
  "nvim-telescope/telescope-frecency.nvim",
  -- install the latest stable version
  version = "*",
  config = function()
    require("telescope").load_extension "frecency"
  end,
}

2.0.0 changes the scoring and the database format

The upgrade notice is the most important part of the README for anyone tracking master, and it opens with a warning that 2.0.0 is a breaking release.

The minimum Neovim is bumped to v0.11.7, and the plugin refuses to load on older versions. The default database format changes from v1 to v2, and the first launch on 2.0.0 automatically migrates the existing file_frecency.bin to file_frecency_v2.bin and prints a one-time vim.notify. The v1 file is preserved on disk, so you can roll back by pinning to ^1.0.0.

Rankings will shift after the migration because the score algorithm changed, and the README names both formulas: v1 was count times static recency, and v2 is exponential decay. The underlying data is intact, so this is a re-scoring rather than a reset.

Two API changes follow. The query function called with record = true no longer returns a timestamps array, and you get the most recent access epoch from reference_time plus last_accessed instead, a single value rather than a list. The count field is preserved as an alias for num_accesses. And the db_version config option is removed.

The design here is careful in a way that is worth crediting. The breaking change is announced, the migration is automatic, the old data is kept, the rollback is a version pin, and the help topic :help telescope-frecency-database-v2-migration holds the full story.

Day to day use and the test script

Using the extension from the command line is a matter of one command with optional arguments.

:Telescope frecency
" Use a specific workspace tag:
:Telescope frecency workspace=CWD
" You can use with telescope's options
:Telescope frecency workspace=CWD path_display={"shorten"} theme=ivy

The last line shows that telescope's own options still work, which is the point of being an extension rather than a separate picker. The workspace argument takes a tag, and the path_display and theme options pass through to telescope.

Filter tags can also be applied by typing the :tag: name with surrounding colons directly in the finder query, and entering :<Tab> triggers omni completion for the available tags, again in the case where enabled_prompt_mappings is true.

For development, the repository includes unit tests and a script to run them.

# Run this in /path/to/telescope-frecency.nvim
bin/run-tests

Running bin/run-tests with -h gives more details. The tree itself is small and conventional for a Neovim plugin, with lua for the source, doc for the help files, bin for scripts, and tooling configuration at the root including a .stylua.toml, a .luacheckrc and a .luarc.json.

The release history is steady rather than fast, with 1.2.2 from 2025-09-27, 1.2.1 from 2025-03-03 and 1.2.0 from 2025-02-14, and the last push was on 2026-09-07.

Editorial conclusion

Adopt telescope-frecency.nvim if your file picker habit has degraded into scrolling through a long list of alphabetically similar filenames, and if you work across several projects where the interesting file changes from day to day. Do not adopt it if your Neovim is older than 0.11.7 without pinning to the v1 line, because the 2.0 release refuses to load, and remember that the plugin only reorders what it can find, so it will not surface a file that was never opened. Before you switch, pin deliberately: read the 2.0.0 migration notes, since the scoring changes from count times static recency to exponential decay and the rankings will shift once, and install fd or ripgrep, because the workspace listing is far faster with them than with the built-in Lua fallback.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nvim-telescope/telescope-frecency.nvim on GitHub
4. README
5. Releases