Extremely simple CLI tool for maintaining a frecency history.
The intended use case is to add a frecency-based search history to CLI tools like dmenu, rofi, or fzf.
It also allows you to easily emulate popular directory-jumping tools like autojump or z.
We'll look at some examples of how to integrate
frecently with other tools.
For more detailed information, run
$ frecently view .history # .history doesn't exist yet. By default, all commands treat a missing file as empty
$ frecently bump .history foo # creates .history, and bumps foo
$ frecently bump .history bar
$ frecently view .history # `view` shows all entries, ordered by frecency
$ echo -e "bar\nbaz" | frecently view .history --augment # with --augment, frecently accepts extra entries on stdin (newline-separated) that should always appear in the output
$ echo -e "foo\nbar\nbaz" | frecently scores .history --augment # `scores` has the same interface as `view`, but shows the entire scores table
weighted score hourly daily monthly
178.663539 0.985473 0.999390 0.999980 bar
178.267277 0.983010 0.999286 0.999976 foo
0.000000 0.000000 0.000000 0.000000 baz
$ echo -e "bar\nbaz" | frecently view .history --augment --restrict # with --restrict, we exclusively output entries that appear on stdin
This bash script shows how easily
frecently integrates with tools like
set -eo pipefail
QUERY=$(frecently view $HISTORY | dmenu -p "Web search:")
if [[ -n "$QUERY" ]]; then
frecently bump "$HISTORY" "$QUERY"
In this more complicated bash script, we use
dmenu to first ask the user for a directory, and then open a terminal in that directory.
It shows a good use-case for
-a), augmenting the list with any non-hidden directory at most 2 deep from
set -eo pipefail
# First, purge non-existent directories from the history
for dir in $(frecently view $HISTORY); do
if [ ! -d "$dir" ]; then
echo "Removing $dir"
frecently delete $HISTORY "$dir"
# Load the history, augmenting it with every non-hidden directory at most 2 deep from $HOME.
DIR=$(find $HOME -maxdepth 2 -type d -not -path '*/.*' | frecently view $HISTORY -a | dmenu -i)
if [ -d $DIR ]; then
frecently bump $HISTORY "$DIR"
$TERMCMD -d "$DIR"
This kind of script is especially useful when combined with a shell hook that bumps on every directory change, to get
fish, that looks like this:
function __frecently-directory-hook --on-variable PWD --description 'bump current directory in history'
frecently bump /path/to/history/file "$PWD"
The GitHub Action CI builds static binaries for x86 and aarch64, so look for the artifacts there.
If this project gains traction (stars) I'll add proper releases so the artifacts don't get deleted after 90 days.
Compiling from source
frecently can be built using a Haskell build tool, or using Nix.
Using Cabal, run
Using Nix, the
flake.nix file exposes the executable both directly and as an overlay.
frecently works by maintaining three energy levels per entry.
The energy levels decay exponentially, with half-lives of an hour, a day, and a month, respectively.
bump an entry by adding 1 to each of these.
An entry's frecency score is calculated by multiplying each of these three energies by a weight.
The weights default to 720, 30, and 1, for the hourly, daily, and monthly energies, respectively, but can be overridden on the CLI.
Energies are updated only when the history file is used in a
touch command, and when we do, we update every entry's energy simultaneously.
This is invisible to the user, but it ensures that we only need to calculate decay factors once when opening a file, making score calculations very efficient.
When, during an update, an entry's monthly energy drops below the threshold value (defaults to 0.1), it is deleted from the history.
If you don't want items to be deleted, use a threshold of 0.
This tool was inspired by frece.
I really like the idea behind
frece, but I think the execution is more complicated than it needs to be.
frecently is both simpler and easier to integrate into CLI applications.