ShannonMax: A Library to Optimize Emacs Keybindings with Information Theory

Source: Hacker News

ShannonMax uses information theory to analyze your Emacs usage and suggest better keybindings.
It helps you find commands where changing the keybinding can significantly reduce the amount you type.

🔗 Project page

Warning: When using a keylogger, be careful not to log any sensitive information!

Cite this software
Straus, S. (2024). Better Keybindings with Information Theory [Computer software]. Retrieved from https://github.com/sstraust/shannonmax

Original talk – Better Keybindings with Information Theory – YouTube

How to Use

1. Download the required files

   • shannon-max.el
   • target/emacskeys-0.1.0‑SNAPSHOT‑standalone.jar

2. Place them in the same directory that is on your Emacs load‑path, e.g.:

   ~/.emacs.d/custom/shannon-max.el
   ~/.emacs.d/custom/target/emacskeys-0.1.0-SNAPSHOT-standalone.jar

3. Add the following to your ~/.emacs (or init.el):

   ;; Add the directory to Emacs' load‑path
   (add-to-list 'load-path "~/.emacs.d/custom")
   
   ;; Load the shannon‑max package
   (require 'shannon-max)
   
   ;; Tell the package where the JAR file lives
   (setq shannon-max-jar-file
         (expand-file-name "~/.emacs.d/custom/target/emacskeys-0.1.0-SNAPSHOT-standalone.jar"))

4. Make sure Java (the JVM) is installed on your machine and the JAR file is executable:

   chmod +x ~/.emacs.d/custom/target/emacskeys-0.1.0-SNAPSHOT-standalone.jar

5. Start collecting key‑logging data

   Add the following line to your Emacs configuration (or evaluate it manually):

   (shannon-max-start-logger)

   After a few minutes, verify that data is being written to ~/emacs-logged-keys.

6. Analyze the collected data

   When you have enough samples, run:

   M-x shannon-max-analyze

   The command will display the Shannon entropy analysis of your Emacs key usage.

Viewing the Output

You can invoke the analysis at any time with:

M-x shannon-max-analyze

In the results buffer the following key bindings are available:

Interpreting the Results

Shannonmax compares the actual length of a keybinding (e.g., "x e" has length 2) with its theoretical length – the length it should have based on how often you use it.
The theoretical length is derived from information‑theoretic analysis of your logged command usage.

• Frequent commands → should have shorter keybindings.
• Infrequent commands → can tolerate longer keybindings.

Typical workflow

1. Identify keybindings that are too long for frequently used commands.
2. Rebind them to shorter, more convenient sequences.
3. If you run out of convenient keys, consider unbinding keybindings that are too short for rarely used commands to free up space.

For a visual walkthrough, watch the tutorial video:
Shannonmax Overview (YouTube)

Customizing the Behavior

shannon-max-custom-keypress-cost

By default, shannon‑max assumes every keypress costs 1.
Sequences that contain control characters incur an additional cost of 1 per control character.

Examples

If you prefer a different cost model, provide your own cost function and adjust the alphabet size accordingly (see below).

shannon-max-alphabet-size

This variable represents how many distinct commands can be produced with a single keypress.
It is used to compute the theoretical length of a given key command.

• With only 2 keys, keybindings must be relatively long to encode all possible commands.
• With 100 keys, keybindings can be much shorter.

The default assumes 52 keys (A–Z and a–z) and a cost of 1 per keypress.

If you change the cost function, recalculate the appropriate alphabet size for your new cost‑weighted “keyboard”. The proper way is to solve the characteristic equation described in Shannon’s paper (see page 3):

Future work will automate this calculation.
In the meantime, you can experiment with the value until the results look reasonable; you’ll still obtain useful, actionable output.

shannon-max-filtered-commands

A list of Emacs commands to ignore in the output.
By default, commands matching "lambda", "(", or "[" are filtered out—useful for excluding the self‑insert command and similar items.

shannon-max-filter-commands-fn

A function that performs the same filtering as shannon-max-filtered-commands, but allows you to implement custom logic for excluding commands.

Known Limitations

Keylogger Limitations

Certain packages interfere with the keylogger’s ability to correctly log commands.
shannonmax uses real-last-command and this-command-keys-vector inside post-command-hook to determine which keys/commands to log. Packages such as ido-mode can disrupt these values.

We use post-command-hook (instead of pre-command-hook) so that logged keys are correctly captured when god-mode is active.

If you have ideas or work‑arounds, I’d love to hear them!

Better Support for Major/Minor Modes

Some keybindings are only active in specific major or minor modes.
Ideally we would compute separate keymaps for every mode, but doing so correctly—and in a way that remains useful—requires careful design.

Support for Multi‑Command / Arithmetic Codings

To produce the most optimal output, we’d like to recognize pairs or sequences of commonly used Emacs commands and fold them into a single logical keybinding.

More Things to Work On

• Easier installation via MELPA
• More user‑friendly UI menus for rebinding keys (instead of using keymap-global-set)
• Improved handling of capitalized letters

Got other ideas? Feel free to open an issue on the repository! :D