Remap Any Keyboard Key with keyd on Linux Wayland
Iwan Efendi3 min
There'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.
I decided to change that. The plan was simple: remap it to Super + 2, 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.
It did not take fifteen minutes.
On Wayland, the classic
Don't guess. Use
Press the key. In my case, the output was:
The key name is
Paste this:
I got tripped up on two things before this worked. Here's what to watch:
keyd's modifier shorthand:
Run
That output —
keyd 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:
That's the complete working config. Because keyd runs as a systemd service, this remap persists across every reboot automatically — no startup scripts needed.
That 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,
Why keyd?
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.
Step 1: Install keyd
keyd isn't in the Ubuntu apt repositories by default, so you'll need to build it from source:
1
Install build dependencies and clone the repo
sudo apt install git make gcc -y
git clone https://github.com/rvaiya/keyd
cd keyd2
Build and install
make && sudo make install3
Enable and start the system service
sudo systemctl enable keyd
sudo systemctl start keyd4
Verify the installation
keyd --version
# keyd v2.6.0Step 2: Find the Key Name
keyd monitor to capture the exact name keyd sees for your physical key:
sudo keyd monitorkeyd virtual keyboard 102nd down
keyd virtual keyboard 102nd up
102nd. Write it down — you'll use it in the config file.
Step 3: Create the Config
sudo mkdir -p /etc/keyd
sudo nano /etc/keyd/default.conf[ids]
*
[main]
102nd = M-2| ❌ Wrong | ✅ Correct | Reason |
|---|---|---|
102key | 102nd | Incorrect key name |
meta+2 | M-2 | keyd uses single-letter modifier shortcuts |
| Symbol | Modifier |
|---|---|
M | Meta / Super (Windows key) |
C | Control |
A | Alt |
S | Shift |
Step 4: Restart and Verify
sudo systemctl restart keydkeyd monitor again and press the key. If the remap worked, you'll see:
keyd virtual keyboard leftmeta down
keyd virtual keyboard 2 down
keyd virtual keyboard 2 up
keyd virtual keyboard leftmeta up
leftmeta followed by 2 — is the confirmation you need.
Step 5: Connect to GNOME Custom Shortcut
- Name: Claude (or whatever you want)
- Command:
xdg-open https://claude.ai - Shortcut: Super + 2
Don't Leave the Command Field Empty
keyd will send the correct Super + 2 signal, but GNOME won't respond to it unless a command is actually set. An empty command field means nothing happens.
Final Config
[ids]
*
[main]
102nd = M-2That 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.
Have a different use case for keyd? I'd love to hear what you mapped. Drop a comment below.Topics
Topics in this note
Explore related ideas through the topics connected to this note.
Share this article
Discussion
Preparing the comments area...