keyd-application-mapper(1)

💅 keyd-application-mapper, bestie

okay so this is a page from your General Commands Manual (yes, that kind of manual, the man kind, we love her) and it's all about keyd-application-mapper — the little icon that remaps your keys the second your window focus changes 🦋 honestly? main character energy.

---

✨ NAME ✨

keyd-application-mapper — remap keys when window focus changes 💫

🎀 SYNOPSIS 🎀

keyd-application-mapper [-d|--daemonize] [-v|--verbose]

🌸 OPTIONS 🌸

• -v, --verbose — write verbose output, which lowkey includes printing out every window focus event it detects 👀 you can literally use this output to figure out what a window's class and title actually are, so you can set up mappings for that window in the config file. it's giving "look at me, i'm the diagnostic tool now" 🔍
• -d, --daemonize — daemonize, and write output to ~/.config/keyd/app.log instead of stdout 🫶 (so it goes and lives in the background, cute little log file and all)

💖 DESCRIPTION 💖

it's a script, and what it does is read ~/.config/keyd/app.conf and apply the bindings you supplied whenever a window with a matching class comes into focus ✨

think of each section as a set of application specific masks layered over the global rules defined in /etc/keyd/*.conf — like a little outfit change for each app 💅

the config file has the following form:

         [<filter>]

         <expression 1>
         <expression 2>
         ...

where <filter> has one of the following forms:

         [<class exp>]              # Match by window class
         [<class exp>|<title exp>]  # Match by class and title

and each <expression> is a valid argument to keyd bind (see Bindings) 👑

<class exp> and <title exp> are strings which describe window class and title names to be matched, and may optionally contain unix style wildcards (*). for example, [gnome|*find*] will match any window with a class of gnome and a title containing the substring find 🧚

E.G:

         [kitty]

         alt.] = C-tab
         alt.[ = C-S-tab
         alt.t = C-S-t

         [st-*]

         alt.1  = macro(Inside space st)

         [chromium]

         control.1 = macro(Inside space chrome!)
         alt.] = C-tab
         alt.[ = C-S-tab
         alt.t = C-t

will remap A-1 to the the string 'Inside st' when a window with a class that begins with 'st-' (e.g st-256color) is active 🔥

window class and title names can be obtained by inspecting the output if the program was started with the -v, --verbose option. if the program was daemonized, you can read the log file output by e.g. tail -f ~/.config/keyd/app.log. a reload may be triggered by sending the script a USR1 signal 📡 (iykyk)

at the moment X, Sway and Gnome are supported 🌈

⭐ INSTALLATION ⭐

installation is a simple matter of running the command keyd-application-mapper -d somewhere in your display server initialization logic (e.g ~/.xinitrc or ~/.xsession) 🎀 if you are running Gnome, running keyd-application-mapper for the first time will install an extension which manages the script lifecycle 🦋

in order for this to work, keyd must be running and the user must have access to /var/run/keyd.socket (i.e be a member of the keyd group) 🔑

💜 ENVIRONMENT VARIABLES 💜

• KEYD_DEBUG — debug log level. 0,1 can be specified (default: 0).

---

🚨 A note on security 🚨

any user which can interact with a program that directly controls input devices should be assumed to have full access to the system. no cap, that's just how it is 😭

while keyd offers slightly better isolation compared to other remappers by dint of mediating access through an IPC mechanism (rather than granting users blanket access to /dev/input/* and /dev/uinput), it still provides an opportunity for abuse and should be treated with due deference 🙈

specifically, access to /var/run/keyd.socket should only be granted to trusted users and the group keyd should be regarded with the same reverence as wheel 👑💀

---

and that's the whole page bestie 🫶 this gorgeous thing is dated 2025-09-11 and it's keyd-application-mapper(1), signing off — mwah, slay, periodt 💅✨🌸