gitwtfhub

wtf is xkeysnail?

evankrall/xkeysnail — explained in plain English

Analysis updated 2026-08-10 · repo last pushed 2024-01-16

Audience · developerComplexity · 3/5DormantSetup · moderate

TL;DR

A Linux keyboard remapping tool that lets you create complex, context-sensitive key mappings that change behavior depending on which app you're using, written as a Python config file.

Mindmap

mindmap
  root((repo))
    What it does
      Remaps keys at system level
      Context-aware per application
      Emacs bindings everywhere
    Configuration
      Python config file
      Condition-based keymaps
      Run custom Python code
    Use cases
      Emacs shortcuts globally
      App-specific keybindings
      Two-step shortcut chains
    Limitations
      Requires root privileges
      X11 only not Wayland
    Audience
      Linux power users
      Emacs enthusiasts

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Make Emacs-style keyboard shortcuts work across all applications on Linux.

REASON 2

Set different key mappings for Firefox versus your terminal.

REASON 3

Create two-step shortcuts like Ctrl-x then Ctrl-c for specific apps.

REASON 4

Run custom Python code when a particular key combination is pressed.

What's in the stack?

PythonLinuxX11

How it stacks up

evankrall/xkeysnail000madz000/rfid-attendance00kaku/gallery-slider-block
LanguageTypeScriptJavaScript
Last pushed2024-01-162024-07-222021-05-19
MaintenanceDormantDormantDormant
Setup difficultymoderateeasyeasy
Complexity3/52/52/5
Audiencedeveloperdevelopergeneral

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · moderate Time to first run · 30min

Requires root privileges to run and only works on Linux systems using the X window system, not Wayland.

No license information was provided in the explanation, so the licensing terms are unknown.

Wtf does this do

xkeysnail is a keyboard remapping tool for Linux systems running the X window system. It lets you change what your keys do, not just simple swaps like turning Caps Lock into Ctrl, but complex, context-sensitive remappings that behave differently depending on which application you're using. If you've ever wanted Emacs-style shortcuts everywhere, or wished a specific key combo did something different in Firefox versus your terminal, this is the kind of tool that makes that possible. The tool works at a low level in the Linux input system, which means your remappings apply almost everywhere, not just in applications that explicitly support custom shortcuts. You write a Python configuration file that defines keymaps, each with a condition and a set of mappings. The condition can match a specific application (by its internal window class name), or you can set a global keymap that always applies. Mappings can remap a single key to another, chain multiple actions together, define two-step shortcuts like Ctrl-x then Ctrl-c, or even run arbitrary Python code when a key is pressed. The example config ships with Emacs-like bindings that work across most applications, which is a common use case. This is primarily for power users on Linux who want fine-grained control over their keyboard layout, developers who live in Emacs-style keybindings but need to use other apps, people switching between different keyboard habits, or anyone who wants application-specific shortcut behavior. The tradeoff is that it requires root privileges to run, since it operates at the system input level. It also only works with X, not newer display servers like Wayland. The configuration is done entirely through a Python file, so some comfort with basic Python syntax helps, though the example config provides patterns you can adapt without deep programming knowledge.

Yoink these prompts

Prompt 1
Help me write an xkeysnail Python config that makes Emacs-style shortcuts work everywhere, but switches to normal bindings when I'm using a terminal.
Prompt 2
I have xkeysnail installed. Write a config snippet that remaps Caps Lock to Ctrl globally and adds a two-step shortcut Ctrl-x then Ctrl-s that triggers Ctrl-s in Firefox only.
Prompt 3
Show me how to write an xkeysnail keymap condition that matches a specific application by its window class name, and explain how I can find the window class of any app.
Prompt 4
Adapt the xkeysnail example Emacs config so that it also runs a custom Python function when I press Ctrl-Shift-K.

Frequently asked questions

wtf is xkeysnail?

A Linux keyboard remapping tool that lets you create complex, context-sensitive key mappings that change behavior depending on which app you're using, written as a Python config file.

Is xkeysnail actively maintained?

Dormant — no commits in 2+ years (last push 2024-01-16).

What license does xkeysnail use?

No license information was provided in the explanation, so the licensing terms are unknown.

How hard is xkeysnail to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is xkeysnail for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.