keyd-application-mapper(1) General Commands Manual keyd-application-mapper(1)

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

keyd-application-mapper [-d]

A script which reads ~/.config/keyd/app.conf and applies the supplied bindings whenever a window with a matching class comes into focus.

You can think of each section as a set of application specific masks applied over the global rules defined in /etc/keyd/*.conf.

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 log output while the daemon is running (e.g tail -f ~/.config/keyd/app.log). A reload may be triggered by sending the script a USR1 signal.

At the moment X, Sway and Gnome are supported.

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).

KEYD_DEBUG

Debug log level. 0,1 can be specified (default: 0).

Any user which can interact with a program that directly controls input devices should be assumed to have full access to the system.

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.

2024-07-27