keypal

Spaced-repetition practice for keyboard shortcuts. Build muscle memory for the shortcuts you actually use, scheduled with FSRS.

Why a desktop app?

• Browsers can't capture most shortcuts. Browsers intercept Ctrl+W, Ctrl+T, Ctrl+N, Ctrl+Q, etc. at the OS level before JavaScript sees them.
• Terminals intercept some shortcuts too. Terminal emulators eat shortcuts like Ctrl+Shift+F, and terminal protocols have byte collisions (Ctrl+H = Backspace, Ctrl+I = Tab).
• A Qt window captures keys cleanly. No byte collisions, no terminal-emulator interception, full modifier support.

Install

Linux (no Python required): download the .flatpak from GitHub Releases and install it:

flatpak install KeyPal-x.x.x-x86_64.flatpak

Any platform with uv installed:

uv tool install keypal

Or run without installing:

uvx keypal

To run from source (you may need to uv tool install rust-just first):

git clone https://github.com/treyhunner/keypal
cd keypal
uv sync
just run

Built-in packs

The tmux and obsidian packs are hybrid: a curated list of common shortcuts with friendly descriptions, with your actual key bindings substituted in if you have customs. Change a binding in tmux or Obsidian, restart keypal, and the pack reflects it.

A shared_id mechanism lets shortcuts in different packs share the same FSRS card. Practice Ctrl+A in readline and it counts toward python_repl too (since the Python REPL uses readline under the hood).

Using the app

Home screen

In a quiz session

After a correct answer, three dots fill in left to right over three seconds, then auto-advances. Press Enter any time to skip the wait.

After a wrong answer

You'll see what you pressed (red), the expected combo (green), and a hint with your options. Press the correct combo to advance with practice credit, or use the keys above to skip / claim correct / dismiss.

Storage

Your data lives in ~/.local/share/keypal/ on Linux (platform-equivalent elsewhere via platformdirs):

• cards.json: FSRS state for each shortcut you've practiced
• review_log.jsonl: append-only log of every review
• aliases.json: alternative key combos you've taught keypal (via Y on a wrong answer)
• disabled.json: shortcuts you've dismissed with F4
• seen.json: tracks which shared shortcuts have been introduced in each pack
• selected_packs.json: which packs are checked for multi-pack practice
• settings.json: your settings (new cards per session, threshold overrides)

Override the location with the KEYPAL_DATA_DIR environment variable.

Limitations

• Your desktop environment may intercept a few shortcuts (e.g. Alt+F4 to close windows). Use the diagnostic screen (D) to confirm what keypal receives.
• Keys that physically exist on the keyboard but aren't in keypal (rare combos, complex chords beyond two keys) need to be added to a pack manually.

Contributing

See AGENTS.md for code conventions, project layout, and common gotchas.

just qa     # format + lint + test
just test   # tests only