{"slug":"remap-keyboard-key-keyd-wayland-linux","locale":"en","isFallback":false,"translationAvailable":["en","id"],"translationUrls":{"en":"/api/notes/remap-keyboard-key-keyd-wayland-linux?locale=en","id":"/api/notes/remap-keyboard-key-keyd-wayland-linux?locale=id"},"title":"Remap Any Keyboard Key with keyd on Linux Wayland","description":"How I remapped an unused key on my MSI Modern 14 to launch Claude with one keystroke using keyd — the cleanest way to remap keys on Linux Wayland.","date":"2026-03-29","updated":null,"tags":["linux","ubuntu","keyd","keyboard","wayland"],"content":"\nThere's a key in the bottom-right corner of my MSI Modern 14 keyboard — wedged between Alt GR and Fn — that I had never pressed since the day I got the laptop. Not a bad key. Just... permanently idle.\n\nI decided to change that. The plan was simple: remap it to <kbd>Super</kbd> + <kbd>2</kbd>, which I'd already assigned to open Claude in GNOME. One key press, straight to the AI I use for almost everything — coding, writing, debugging. I figured it would take fifteen minutes.\n\nIt did not take fifteen minutes.\n\n## Why keyd?\n\nOn Wayland, the classic `xmodmap` approach doesn't work anymore — it depends on X11. `keyd` operates at the kernel input level, so it's completely display-server agnostic. X11, Wayland, doesn't matter. The config syntax is clean once you understand it.\n\n## Step 1: Install keyd\n\n`keyd` isn't in the Ubuntu apt repositories by default, so you'll need to build it from source:\n\n<Steps>\n  <Step>\n\n### Install build dependencies and clone the repo\n\n```bash\nsudo apt install git make gcc -y\n\ngit clone https://github.com/rvaiya/keyd\ncd keyd\n```\n\n  </Step>\n  <Step>\n\n### Build and install\n\n```bash\nmake && sudo make install\n```\n\n  </Step>\n  <Step>\n\n### Enable and start the system service\n\n```bash\nsudo systemctl enable keyd\nsudo systemctl start keyd\n```\n\n  </Step>\n  <Step>\n\n### Verify the installation\n\n```bash\nkeyd --version\n# keyd v2.6.0\n```\n\n  </Step>\n</Steps>\n\n## Step 2: Find the Key Name\n\nDon't guess. Use `keyd monitor` to capture the exact name keyd sees for your physical key:\n\n```bash\nsudo keyd monitor\n```\n\nPress the key. In my case, the output was:\n\n```\nkeyd virtual keyboard    102nd down\nkeyd virtual keyboard    102nd up\n```\n\nThe key name is `102nd`. Write it down — you'll use it in the config file.\n\n## Step 3: Create the Config\n\n```bash\nsudo mkdir -p /etc/keyd\nsudo nano /etc/keyd/default.conf\n```\n\nPaste this:\n\n```ini\n[ids]\n*\n\n[main]\n102nd = M-2\n```\n\nI got tripped up on two things before this worked. Here's what to watch:\n\n| ❌ Wrong | ✅ Correct | Reason |\n|---|---|---|\n| `102key` | `102nd` | Incorrect key name |\n| `meta+2` | `M-2` | keyd uses single-letter modifier shortcuts |\n\nkeyd's modifier shorthand:\n\n| Symbol | Modifier |\n|---|---|\n| `M` | Meta / Super (Windows key) |\n| `C` | Control |\n| `A` | Alt |\n| `S` | Shift |\n\n## Step 4: Restart and Verify\n\n```bash\nsudo systemctl restart keyd\n```\n\nRun `keyd monitor` again and press the key. If the remap worked, you'll see:\n\n```\nkeyd virtual keyboard    leftmeta down\nkeyd virtual keyboard    2 down\nkeyd virtual keyboard    2 up\nkeyd virtual keyboard    leftmeta up\n```\n\nThat output — `leftmeta` followed by `2` — is the confirmation you need.\n\n## Step 5: Connect to GNOME Custom Shortcut\n\nkeyd sends the remapped signal, but GNOME still needs to know what to do with it. Open **Settings → Keyboard → Custom Shortcuts** and add a new entry:\n\n- **Name:** Claude (or whatever you want)\n- **Command:** `xdg-open https://claude.ai`\n- **Shortcut:** <kbd>Super</kbd> + <kbd>2</kbd>\n\n<Callout variant=\"warning\" title=\"Don't Leave the Command Field Empty\">\n  keyd will send the correct <kbd>Super</kbd> + <kbd>2</kbd> signal, but GNOME won't respond to it unless a command is actually set. An empty command field means nothing happens.\n</Callout>\n\n## Final Config\n\n```ini\n[ids]\n*\n\n[main]\n102nd = M-2\n```\n\nThat's the complete working config. Because keyd runs as a systemd service, this remap persists across every reboot automatically — no startup scripts needed.\n\n---\n\nThat idle key now has exactly one job: open Claude instantly, from wherever I am on the desktop. If you have a similar orphaned key on your keyboard, `keyd` is the cleanest way to put it to work on Linux — especially on Wayland. Just make sure the key name and modifier syntax are right from the start, and the rest takes care of itself.\n\nHave a different use case for keyd? I'd love to hear what you mapped. Drop a comment below.\n"}