diff --git a/.woodpecker.yml b/.woodpecker.yml
index 60e18dc..ff38c43 100644
--- a/.woodpecker.yml
+++ b/.woodpecker.yml
@@ -4,7 +4,8 @@ pipeline:
     commands:
       - /opt/bats/bin/bats test
 
-  release-prep: # prepare changelog and version information for release candidate
+  release-prep:
+    # prepare changelog and version information for release candidate
     when:
       event: tag
       tag: v*
@@ -13,7 +14,8 @@ pipeline:
       - sed -ne 's/bm_version=\(.*\)/\1/p' bemoji > NEWEST_VERSION.txt
       - awk '/^## \[\d/{p++} p==2{print; exit} p>=1' CHANGELOG.md | head -n -1 | tail -n+3 > NEWEST_CHANGES.txt
 
-  versioncompare: # ensure we correctly bumped versions
+  versioncompare:
+    # ensure we correctly bumped versions
     when:
       event: tag
       tag: v*
@@ -42,9 +44,10 @@ pipeline:
       - cp bemoji build
       - md2man -in README.md -out bemoji.1 && gzip bemoji.1
       - cp LICENSE README.md bemoji.1.gz build/doc
-      - tar -czvf bemoji-$BM_VERSION.tar.gz build/*
-      - zip -r bemoji-$BM_VERSION.zip build/*
-      - mv bemoji-$BM_VERSION.tar.gz bemoji-$BM_VERSION.zip dist
+      - cd build || exit 1
+      - tar -czvf bemoji-$BM_VERSION.tar.gz *
+      - zip -r bemoji-$BM_VERSION.zip *
+      - mv bemoji-$BM_VERSION.tar.gz bemoji-$BM_VERSION.zip ../dist
 
   release-gitea:
     group: release
@@ -70,7 +73,7 @@ pipeline:
       - apk add file jq curl
       - BM_VERSION=$(cat NEWEST_VERSION.txt)
       - BM_CHANGED=$(sed -e 's|#||g' -e 's|^.*$|\0 <br />|' NEWEST_CHANGES.txt) # display newlines workaround
-      - echo "{\"tag_name\":\"$BM_VERSION\",\"target_commitish\":\"main\",\"name\":\"$BM_VERSION\",\"body\":\"$BM_CHANGED\",\"draft\":false,\"prerelease\":false,\"generate_release_notes\":false}" > data.json
+      - echo "{\"tag_name\":\"v${BM_VERSION}\",\"target_commitish\":\"main\",\"name\":\"v${BM_VERSION}\",\"body\":\"$BM_CHANGED\",\"draft\":false,\"prerelease\":false,\"generate_release_notes\":false}" > data.json
       - "response=$(curl -X POST -H \"Accept:\\ application/vnd.github+json\" -H \"Authorization:\\ Bearer $GITHUB_RELEASE_TOKEN\" https://api.github.com/repos/$GITHUB_REPO/releases -d \"@data.json\")"
       - "uploadurl=$(echo $response | jq -r '.upload_url' | cut -d'{' -f1)"
       - "[ $uploadurl = null ] && { echo $response; exit 1; }"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0925518..3b1018c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,15 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-<!-- ### Added -->
+### Added
 
-<!-- ### Changed -->
+- Pass through return code 1 from selection tool
+- (!) Number of displayed recent emoji can be set with `-P` option:
+  This replaces previous `-P` history flag toggle. Use number to set amount of recent
+  entries to display, `-P3`. To completely hide history use `-P0`.
+- Add nerdfont emoji set download with `-D nerd`
+
+### Changed
+
+- (!) History uses `XDG_STATE_HOME` directory by default:
+  This constitutes a break in behavior if you relied a lot on your pick history in the default
+  location. To retain your old history file, simply move it from the old cache directory
+  (`~/.cache/bemoji-history.txt` by default) to the new one (`~/.local/state/bemoji-history.txt`
+  by default).
+- (!) `XDG_CACHE_LOCATION` renamed to `XDG_HISTORY_LOCATION` to better signify its purpose
 
 <!-- ### Deprecated -->
 
 <!-- ### Removed -->
 
-<!-- ### Fixed -->
+### Fixed
+
+- Always download from newest emoji list url
+- Pass selection to custom typing tools through stdin
 
 <!-- ### Security -->
 
diff --git a/LICENSE b/LICENSE
index aa51234..2fb93db 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Marty Oehme
+Copyright (c) 2023 Marty Oehme
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
index ba08616..9b55372 100644
--- a/README.md
+++ b/README.md
@@ -43,10 +43,10 @@ ln -s bemoji/bemoji /usr/local/bin/bemoji
 
 ### Arch Linux
 
-On Arch Linux, bemoji has been packaged for the [AUR](https://aur.archlinux.org/packages/bemoji-git) so it can be installed manually from here or easily with your preferred AUR helper, e.g.:
+On Arch Linux, bemoji has been packaged for the [AUR](https://aur.archlinux.org/packages?K=bemoji) so it can be installed manually from here or easily with your preferred AUR helper, e.g.:
 
 ```bash
-paru -S bemoji-git
+paru -S bemoji # or bemoji-git
 ```
 
 ## 💿 Usage
@@ -78,7 +78,7 @@ bindsym Mod4+Shift+e exec bemoji -t
 For `riverwm`, put the following in `~/.config/river/init`:
 
 ```
-riverctl map normal $mod+Shift E spawn "bemoji -t"
+riverctl map normal Mod4+Shift E spawn "bemoji -t"
 ```
 
 In `sxhkd`, put the following into `~/.config/sxhkd/sxhkdrc`:
@@ -118,10 +118,10 @@ By default, bemoji will sort the list it displays by your most frequently and mo
 To disable this behavior, execute bemoji like the following:
 
 ```bash
-bemoji -P
+bemoji -P 0
 ```
 
-This will stop bemoji from re-ordering your emoji lists before displaying them.
+This will stop bemoji from adding recently used emoji before displaying the list.
 
 You can also stop bemoji from adding any emoji to your history in the first place:
 
@@ -133,25 +133,35 @@ This will not add any of the emoji you pick to your recent emojis.
 Put both together to completely ignore the recent emoji feature of the program:
 
 ```bash
-bemoji -Pp
+bemoji -p -P0
 ```
 
 Like this, you'll be hiding any recent personal emoji and no one will know that you always type 👄🍆💦.
 
+To limit the number of your recently used emoji that are shown without hiding them completely simply increase the number to however many you wish to display. 
+For example, to display only the top 4 recently used emoji:
+
+```bash
+bemoji -P 4
+```
+
 The recent list will also contain emoji that are *not* usually on your lists,
 so kept in single-use lists for example.
 If you don't wish those to show up, make use of these options.
 
-### Setting custom directories
+### Setting custom directories and editing history
 
-By default bemoji stores your recent history in `$XDG_CACHE_HOME/bemoji-history.txt`,
-so most often in `~/.cache/bemoji-history.txt`
+By default bemoji stores your recent history in `$XDG_STATE_HOME/bemoji-history.txt`,
+so most often in `~/.local/state/bemoji-history.txt`
+
+You can edit this file in any text editor to change your recent history,
+removing, adding or changing the emoji appearing there.
 
 You can overwrite the directories bemoji uses for its emoji lists and history files with the following two environment variables:
 
 ```
 BEMOJI_DB_LOCATION=/path/to/my/emoji/directory
-BEMOJI_CACHE_LOCATION=/path/to/my/cache/directory
+BEMOJI_HISTORY_LOCATION=/path/to/my/state/directory
 ```
 
 There are no equivalent commandline arguments to overwrite these two settings.
@@ -174,24 +184,24 @@ The path can also be a weblink which bemoji will download and use:
 bemoji -f "https://raw.githubusercontent.com/jchook/emoji-menu/master/data/emojis.txt"
 ```
 
-### Download additional emoji set
+### Download additional emoji sets
 
 bemoji automatically downloads an emoji list for you to use on first invocation.
-By default, it only downloads emoji, though you can have it download math symbols as well.
+By default, it only downloads emoji, though you can have it download math symbols and nerdfont icons as well.
 To download additional sets, execute bemoji like the following:
 
 ```bash
 bemoji -D all
 ```
 
-This will download *all* default sets bemoji knows - which is currently the default emoji list and a long list of math symbols.
-Other valid options for this setting are `emoji`, `math`, `none`.
+This will download *all* default sets bemoji knows - which is currently the default emoji list, nerd font icons, and a long list of math symbols.
+Other valid options for this setting are `emoji`, `math`, `nerd`, `none`.
 
 ```bash
-bemoji -D "math emoji"
+bemoji -D "math emoji nerd"
 ```
 
-The above command is equivalent as you can mention multiple sets you want downloaded.
+The above command is equivalent to `all` as you can mention multiple sets you want downloaded.
 
 If set to `none` and no files are in the emoji directory,
 bemoji will complain and not show anything.
@@ -222,6 +232,8 @@ BEMOJI_CLIP_CMD="path/to/your/clipboard/tool"
 BEMOJI_TYPE_CMD="path/to/your/xdotool"
 ```
 
+The candidate list (in the case of picker tool) or the picked selection are passed to the tools through stdin.
+
 This is pretty experimental and you'll have to see how well it works for you.
 The setting can not be changed through the commandline alone.
 
@@ -246,16 +258,16 @@ What follows is a list of all environment variables bemoji understands,
 with their default settings
 
 ```bash
-BEMOJI_DB_LOCATION=$XDG_DATA_HOME/bemoji # where the emoji lists reside
-BEMOJI_CACHE_LOCATION=$XDG_CACHE_HOME # where the cache file resides
+BEMOJI_DB_LOCATION="$XDG_DATA_HOME/bemoji" # where the emoji lists reside
+BEMOJI_HISTORY_LOCATION="$XDG_STATE_HOME" # where the state file resides
 BEMOJI_CUSTOM_LIST="" # the custom emoji list to display
 BEMOJI_DOWNLOAD_LIST="" # the default emoji lists to download to database
-BEMOJI_DEFAULT_COMMAND=<clip-tool> # which command to invoke by default
-BEMOJI_PICKER_CMD=bemenu # which picker tool to use
-BEMOJI_CLIP_CMD=wl-copy # which clipboard tool to use
-BEMOJI_TYPE_CMD=wtype # which typing tool to use (ydotool will NOT work)
+BEMOJI_DEFAULT_COMMAND="" # which command to invoke by default
+BEMOJI_PICKER_CMD="bemenu" # which picker tool to use
+BEMOJI_CLIP_CMD="wl-copy" # which clipboard tool to use
+BEMOJI_TYPE_CMD="wtype" # which typing tool to use (ydotool will NOT work)
 BEMOJI_PRIVATE_MODE=false # whether to save new entries
-BEMOJI_IGNORE_RECENT=false # whether to display recent entries
+BEMOJI_LIMIT_RECENT="" # whether to display recent entries
 BEMOJI_ECHO_NEWLINE=true # whether to end the output with a newline character
 ```
 
diff --git a/bemoji b/bemoji
index 723b911..1bb2cc2 100755
--- a/bemoji
+++ b/bemoji
@@ -5,10 +5,10 @@ bm_version=0.3.0
 bm_db_location=${BEMOJI_DB_LOCATION:-"${XDG_DATA_HOME:-$HOME/.local/share}/bemoji"}
 # Setting custom emoji list file location:
 # BEMOJI_CUSTOM_LIST=/my/location/emojis.txt
-# Setting custom recent emoji cache:
-# BEMOJI_CACHE_LOCATION=/path/to/my/recents/directory
-bm_cache_dir="${BEMOJI_CACHE_LOCATION:-${XDG_CACHE_HOME:-$HOME/.cache}}"
-bm_history_file="${bm_cache_dir}/bemoji-history.txt"
+# Setting custom recent emoji history:
+# BEMOJI_HISTORY_LOCATION=/path/to/my/recents/directory
+bm_state_dir="${BEMOJI_HISTORY_LOCATION:-${XDG_STATE_HOME:-$HOME/.local/state}}"
+bm_history_file="${bm_state_dir}/bemoji-history.txt"
 
 # Command to run after user chooses an emoji
 bm_default_cmd="$BEMOJI_DEFAULT_CMD"
@@ -18,7 +18,7 @@ bm_echo_newline=${BEMOJI_ECHO_NEWLINE:-true}
 # Do not save choices
 bm_private_mode=${BEMOJI_PRIVATE_MODE:-false}
 # Do not sort results
-bm_ignore_recent=${BEMOJI_IGNORE_RECENT:-false}
+bm_limit_recent="$BEMOJI_LIMIT_RECENT"
 
 # Report usage
 usage() {
@@ -35,9 +35,9 @@ usage() {
     echo " Other options:"
     echo "   -n             Do not print a newline after the picked emoji."
     echo "   -p             Do not save picked emoji to recent history."
-    echo "   -P             Do not order emoji by recently used."
+    echo "   -P <number>    Limit number of recent emoji to display."
     echo "   -D <choice>    Choose from default lists to download."
-    echo "                  Valid choices: all|none|emoji|math (multiple choices possible)."
+    echo "                  Valid choices: all|none|emoji|math|nerd (multiple choices possible)."
     echo "   -f <filepath>  Use a custom emoji database. Can be a url which will be retrieved."
     echo "   -v             Display current program version and directory configuration."
     echo "   -h             Show this help."
@@ -51,7 +51,7 @@ version() {
 }
 
 # Get Options
-while getopts ":f:D:tcenpPhv" o; do
+while getopts ":f:D:tcenpP:hv" o; do
     case "${o}" in
     f) BEMOJI_CUSTOM_LIST="${OPTARG}" ;;
     t) bm_cmds+=(_typer) ;;
@@ -60,7 +60,7 @@ while getopts ":f:D:tcenpPhv" o; do
     n) bm_echo_newline=false ;;
     D) BEMOJI_DOWNLOAD_LIST="${OPTARG}" ;;
     p) bm_private_mode=true ;;
-    P) bm_ignore_recent=true ;;
+    P) bm_limit_recent="${OPTARG}" ;;
     h) usage 0 ;;
     v) version ;;
     *) usage 1 ;;
@@ -81,6 +81,7 @@ prepare_db() {
         elif echo "$BEMOJI_DOWNLOAD_LIST" | grep -q -e 'all'; then
             dl_default_emoji
             dl_math_symbols
+            dl_nerd_symbols
             return
         else
             if echo "$BEMOJI_DOWNLOAD_LIST" | grep -q -e 'emoji'; then
@@ -89,6 +90,9 @@ prepare_db() {
             if echo "$BEMOJI_DOWNLOAD_LIST" | grep -q -e 'math'; then
                 dl_math_symbols
             fi
+            if echo "$BEMOJI_DOWNLOAD_LIST" | grep -q -e 'nerd'; then
+                dl_nerd_symbols
+            fi
         fi
     fi
     if [ -n "$(find "$bm_db_location" -maxdepth 0 -type d -empty 2>/dev/null)" ]; then
@@ -98,7 +102,7 @@ prepare_db() {
 
 dl_default_emoji() {
     local emojis
-    emojis=$(curl -sSL "https://unicode.org/Public/emoji/14.0/emoji-test.txt")
+    emojis=$(curl -sSL "https://unicode.org/Public/emoji/latest/emoji-test.txt")
     printf "%s" "$emojis" | sed -ne 's/^.*; fully-qualified.*# \(\S*\) \S* \(.*$\)/\1 \2/gp' >"$bm_db_location/emojis.txt"
     printf "Downloaded default emoji set.\n"
 }
@@ -107,6 +111,13 @@ dl_math_symbols() {
         grep -ve '^#' | cut -d';' -f3,7 | sed -e 's/;/ /' >"$bm_db_location/math.txt"
     printf "Downloaded math symbols set.\n"
 }
+dl_nerd_symbols() {
+    local nerd all
+    nerd=$(curl -sSL "https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/css/nerd-fonts-generated.css")
+    all+=$(printf "%s" "$nerd" | sed -ne '/\.nf-/p' -e '/\s*[^_]content:/p' | sed -e 'N;s/^\.nf-\(.*\):before.* content: \"\\\(.*\)\";/\\U\2 \1/')
+    echo -e "$all" > "$bm_db_location/nerdfont.txt"
+    printf "Downloaded nerdfont symbols set.\n"
+}
 
 gather_emojis() {
     if [ -n "$BEMOJI_CUSTOM_LIST" ] && [ -f "$BEMOJI_CUSTOM_LIST" ]; then
@@ -117,31 +128,39 @@ gather_emojis() {
         result=$(cat "$bm_db_location"/*.txt)
     fi
 
-    if [ "$bm_ignore_recent" = true ]; then
+    if [ -n "$bm_limit_recent" ] && [ "$bm_limit_recent" -eq 0 ]; then
         printf "%s" "$result"
-    else
-        printf "%s\n%s" "$(get_most_recent)" "$result" | cat -n - | sort -uk2 | sort -n | cut -f2-
+        return
     fi
+
+    printf "%s\n%s" "$(get_most_recent "$bm_limit_recent")" "$result" | cat -n - | sort -uk2 | sort -n | cut -f2-
 }
 
 get_most_recent() {
+    limit=${1}
     recent_file="$bm_history_file"
     if [ ! -f "$recent_file" ]; then
         touch "$recent_file"
     fi
     # TODO improve this messy line
-    sed -e '/^$/d' "$recent_file" |
+    local result
+    result=$(sed -e '/^$/d' "$recent_file" |
         sort |
         uniq -c |
-        sort -rn |
+        sort -k1rn |
         sed -e 's/^\s*//' |
-        cut -d' ' -f2-
+        cut -d' ' -f2-)
+    if [ -z "$limit" ]; then
+        echo "$result"
+    else
+        echo "$result" | head -n "$limit"
+    fi
 }
 
 add_to_recent() {
     if [ -z "$1" ]; then return; fi
-    if [ ! -d "$bm_cache_dir" ]; then
-        mkdir -p "$bm_cache_dir"
+    if [ ! -d "$bm_state_dir" ]; then
+        mkdir -p "$bm_state_dir"
     fi
     echo "$1" >>"$bm_history_file"
 }
@@ -165,11 +184,14 @@ _clipper() {
 
 # Set default typing uti
 _typer() {
-    totype=$(cat -)
     if [ -n "$BEMOJI_TYPE_CMD" ]; then
         # shellcheck disable=SC2068
         ${BEMOJI_TYPE_CMD[@]}
-    elif [ -n "$WAYLAND_DISPLAY" ] && command -v wtype >/dev/null 2>&1; then
+        return
+    fi
+
+    totype=$(cat -)
+    if [ -n "$WAYLAND_DISPLAY" ] && command -v wtype >/dev/null 2>&1; then
         wtype -s 30 "$totype"
     elif [ -n "$DISPLAY" ] && command -v xdotool >/dev/null 2>&1; then
         xdotool type --delay 30 "$totype"
@@ -206,7 +228,7 @@ result=$(echo "$result" | grep -o '^\S\+' | tr -d '\n')
 
 case "$exit_value" in
 1)
-    exit
+    exit 1
     ;;
 0)
     if [ ${#bm_cmds[@]} -eq 0 ]; then
diff --git a/test/bemoji_cmds.bats b/test/bemoji_cmds.bats
index 2b0a937..ced326c 100644
--- a/test/bemoji_cmds.bats
+++ b/test/bemoji_cmds.bats
@@ -15,8 +15,8 @@ setup() {
 
     # set up small default set of test emoji for each test
     export BEMOJI_DB_LOCATION="$BATS_TEST_TMPDIR/database"
-    export BEMOJI_CACHE_LOCATION="$BATS_TEST_TMPDIR/cache"
-    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_CACHE_LOCATION"
+    export BEMOJI_HISTORY_LOCATION="$BATS_TEST_TMPDIR/history"
+    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_HISTORY_LOCATION"
     cat "$BATS_TEST_DIRNAME/resources/test_emoji.txt" > "$BEMOJI_DB_LOCATION/emoji.txt"
 }
 
@@ -54,6 +54,11 @@ setup() {
 typing result"
 }
 
+@test "Passes selection to custom typer tool through stdin" {
+    BEMOJI_TYPE_CMD="cat -" run bemoji -t 3>&-
+    assert_output "❤️"
+}
+
 @test "Runs custom default command" {
     BEMOJI_DEFAULT_CMD="echo my custom command" run bemoji 3>&-
     assert_output "my custom command"
@@ -64,6 +69,11 @@ typing result"
     assert_output "my clipping"
 }
 
+@test "Returns status code 1 on picker status code 1" {
+    BEMOJI_PICKER_CMD="return 1" run bemoji -e 3>&-
+    assert_failure 1
+}
+
 @test "Prints output with newline by default" {
     bats_require_minimum_version 1.5.0
     BEMOJI_PICKER_CMD="echo heart" run --keep-empty-lines -- bemoji -e
diff --git a/test/bemoji_directories.bats b/test/bemoji_directories.bats
index 28068e1..ede78a0 100644
--- a/test/bemoji_directories.bats
+++ b/test/bemoji_directories.bats
@@ -15,8 +15,8 @@ setup() {
 
     # set up small default set of test emoji for each test
     export BEMOJI_DB_LOCATION="$BATS_TEST_TMPDIR/database"
-    export BEMOJI_CACHE_LOCATION="$BATS_TEST_TMPDIR/cache"
-    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_CACHE_LOCATION"
+    export BEMOJI_HISTORY_LOCATION="$BATS_TEST_TMPDIR/history"
+    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_HISTORY_LOCATION"
     cat "$BATS_TEST_DIRNAME/resources/test_emoji.txt" > "$BEMOJI_DB_LOCATION/emoji.txt"
 }
 
@@ -38,8 +38,8 @@ database=$BATS_TEST_TMPDIR/xdb-db/bemoji
 }
 
 @test "sets XDG directory for history by default" {
-    unset BEMOJI_CACHE_LOCATION
-    export XDG_CACHE_HOME="$BATS_TEST_TMPDIR/xdb-cache"
+    unset BEMOJI_HISTORY_LOCATION
+    export XDG_STATE_HOME="$BATS_TEST_TMPDIR/xdb-cache"
     run bemoji -v
     assert_output --regexp "
 history=$BATS_TEST_TMPDIR/xdb-cache/bemoji-history.txt$"
@@ -54,10 +54,10 @@ database=$HOME/.local/share/bemoji
 }
 
 @test "falls back to default history location if no XDG found" {
-    unset BEMOJI_CACHE_LOCATION
+    unset BEMOJI_HISTORY_LOCATION
     run bemoji -v
     assert_output --regexp "
-history=$HOME/.cache/bemoji-history.txt$"
+history=$HOME/.local/state/bemoji-history.txt$"
 }
 
 @test "BEMOJI_DB_LOCATION sets correct db directory" {
@@ -67,8 +67,8 @@ database=$BATS_TEST_TMPDIR/database
 "
 }
 
-@test "BEMOJI_CACHE_LOCATION sets correct cache directory" {
+@test "BEMOJI_HISTORY_LOCATION sets correct history directory" {
     run bemoji -v
     assert_output --regexp "
-history=$BATS_TEST_TMPDIR/cache/bemoji-history.txt$"
+history=$BATS_TEST_TMPDIR/history/bemoji-history.txt$"
 }
diff --git a/test/bemoji_download.bats b/test/bemoji_download.bats
index 6fda12b..707aaf7 100644
--- a/test/bemoji_download.bats
+++ b/test/bemoji_download.bats
@@ -38,3 +38,11 @@ emoji2 picked up"
     assert_equal "$outcome" "Σ GREEK CAPITAL LETTER SIGMA"
     unstub curl
 }
+@test "Runs nerdfont download on -D nerd option" {
+    stub curl \
+        "printf 'meangingless\nafiller lines\n.nf-md-pipe_wrench:before { \n content: \"\\\f1354\";\n }'"
+    run bemoji -D nerd 3>&-
+    outcome=$(cat "$BEMOJI_DB_LOCATION/nerdfont.txt")
+    assert_equal "$outcome" "󱍔 md-pipe_wrench"
+    unstub curl
+}
diff --git a/test/bemoji_history.bats b/test/bemoji_history.bats
new file mode 100644
index 0000000..82d7394
--- /dev/null
+++ b/test/bemoji_history.bats
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+
+setup_file() {
+    # make bemoji executable from anywhere relative to current testfile
+    TEST_DIR="$( cd "$( dirname "$BATS_TEST_FILENAME" )" >/dev/null 2>&1 && pwd )"
+    PATH="$TEST_DIR/..:$PATH"
+}
+
+setup() {
+    load 'test_helper/bats-support/load'
+    load 'test_helper/bats-assert/load'
+
+    # mock out interactive picker for static emoji return
+    export BEMOJI_PICKER_CMD="echo ❤️"
+
+    # set up small default set of test emoji for each test
+    export BEMOJI_DB_LOCATION="$BATS_TEST_TMPDIR/database"
+    export BEMOJI_HISTORY_LOCATION="$BATS_TEST_TMPDIR/history"
+    mkdir -p "$BEMOJI_DB_LOCATION" "$BEMOJI_HISTORY_LOCATION"
+    cat "$BATS_TEST_DIRNAME/resources/test_emoji.txt" > "$BEMOJI_DB_LOCATION/emoji.txt"
+}
+
+@test "sorts by frecency" {
+    echo -e "there\nhello\nhello" > "$BEMOJI_HISTORY_LOCATION/bemoji-history.txt"
+    echo -e "database" > "$BEMOJI_DB_LOCATION/emoji.txt"
+    BEMOJI_CLIP_CMD="cat -" BEMOJI_PICKER_CMD="cat -" run bemoji 3>&-
+    assert_output "hellotheredatabase"
+}
+
+@test "history limiting uses sorted results" {
+    echo -e "zany\nmy\nisee\nonomatopeia" > "$BEMOJI_HISTORY_LOCATION/bemoji-history.txt"
+    echo -e "database" > "$BEMOJI_DB_LOCATION/emoji.txt"
+    BEMOJI_CLIP_CMD="cat -" BEMOJI_PICKER_CMD="cat -" run bemoji -P 1 3>&-
+    assert_output "iseedatabase"
+}
+
+@test "history limiting takes frecency into account" {
+    echo -e "there\nfriend\nhello\nhello" > "$BEMOJI_HISTORY_LOCATION/bemoji-history.txt"
+    echo -e "database" > "$BEMOJI_DB_LOCATION/emoji.txt"
+    BEMOJI_CLIP_CMD="cat -" BEMOJI_PICKER_CMD="cat -" run bemoji -P 1 3>&-
+    assert_output "hellodatabase"
+}
+
+@test "-P 0 disables history" {
+    echo -e "there\nfriend\nhello\nhello" > "$BEMOJI_HISTORY_LOCATION/bemoji-history.txt"
+    echo -e "database" > "$BEMOJI_DB_LOCATION/emoji.txt"
+    BEMOJI_CLIP_CMD="cat -" BEMOJI_PICKER_CMD="cat -" run bemoji -P 0 3>&-
+    assert_output "database"
+}
+
+@test "BEMOJI_LIMIT_RECENT=0 disables history" {
+    echo -e "there\nfriend\nhello\nhello" > "$BEMOJI_HISTORY_LOCATION/bemoji-history.txt"
+    echo -e "database" > "$BEMOJI_DB_LOCATION/emoji.txt"
+    BEMOJI_LIMIT_RECENT=0 BEMOJI_CLIP_CMD="cat -" BEMOJI_PICKER_CMD="cat -" run bemoji 3>&-
+    assert_output "database"
+}
+