frecently

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.

Examples

We'll look at some examples of how to integrate frecently with other tools. For more detailed information, run frecently --help.

Basic CLI:

$ 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
bar
foo
$ 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
bar
foo
baz
$ 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
bar
baz

dmenu web searches with history

This bash script shows how easily frecently integrates with tools like dmenu:

set -eo pipefail
HISTORY=~/.search-history
QUERY=$(frecently view $HISTORY | dmenu -p "Web search:")

if [[ -n "$QUERY" ]]; then
  frecently bump "$HISTORY" "$QUERY"
  xdg-open "https://www.duckduckgo.com/?q=$QUERY"
fi

Directory picker

In this more complicated bash script, we use frecently and dmenu to first ask the user for a directory, and then open a terminal in that directory. It shows a good use-case for --augment (-a), augmenting the list with any non-hidden directory at most 2 deep from $HOME.

set -eo pipefail
HISTORY=~/.directory-history
# 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"
  fi
done
# 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"
fi

This kind of script is especially useful when combined with a shell hook that bumps on every directory change, to get autojump-like behavior. For 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"
end

Installation

Binaries

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 cabal build.

Using Nix, the flake.nix file exposes the executable both directly and as an overlay.

Implementation details

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. We 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 bump or 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.

Comparison with other tools

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.