term-keys is a package which allows configuring Emacs and a supported terminal emulator to handle keyboard input involving any combination of keys and modifiers.

I created it out of frustration with trying to get work done remotely, while I was abroad. Even with the help of aconfmgr, I still had projects that would be too cumbersome to have their development environment replicated locally. I was also experimenting with working on my phone + Bluetooth keyboard at the time.

Emacs allows remote interaction through two methods: X11 forwarding and TTY. Unfortunately, even though X11 forwarding works great on LAN and Wi-Fi, it doesn’t do so great when the latency is high, as the protocol requires many round-trips for most meaningful operations; which leaves TTY.

TTY’s biggest problem is its inherent limitations, a big one of which is the set of supported key / modifier combinations. Key combinations such as Shift+Up, Alt+Up or Shift+F1 often don’t work correctly (due to variations and inconsistency in their encoding), while others like Ctrl+1 or Ctrl+Shift+A are entirely unrepresentable.

Luckily, many popular terminal emulators allow configuring how key presses map onto control codes, and Emacs can be configured as to how it interprets control codes back into keypresses. Thus enters term-keys: an Emacs package which generates a configuration for your terminal specifying unambiguous encodings of keys as specified by you, and then configures Emacs to understand these encodings.

More information and setup instructions can be found in the README.

Note: this article is back-dated, and was originally written on 2018-11-06.