{"id":13499989,"url":"https://github.com/rvaiya/keyd","last_synced_at":"2025-05-13T19:11:00.036Z","repository":{"id":37020252,"uuid":"389238061","full_name":"rvaiya/keyd","owner":"rvaiya","description":"A key remapping daemon for linux.","archived":false,"fork":false,"pushed_at":"2025-04-05T02:27:25.000Z","size":2285,"stargazers_count":3628,"open_issues_count":124,"forks_count":192,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-04-27T20:01:59.963Z","etag":null,"topics":["c","keyboard","keyboard-layout","keyboard-mapping","keyboard-remap","keymap","linux","sway","x11"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rvaiya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-25T02:03:13.000Z","updated_at":"2025-04-27T17:18:43.000Z","dependencies_parsed_at":"2023-11-11T02:26:55.732Z","dependency_job_id":"a1ea7772-aebb-42ee-bc82-0dff42f4b2ed","html_url":"https://github.com/rvaiya/keyd","commit_stats":{"total_commits":394,"total_committers":27,"mean_commits":"14.592592592592593","dds":"0.10659898477157359","last_synced_commit":"d2ef4ab979d144302e75cd651deb1df28a6f9502"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvaiya%2Fkeyd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvaiya%2Fkeyd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvaiya%2Fkeyd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rvaiya%2Fkeyd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rvaiya","download_url":"https://codeload.github.com/rvaiya/keyd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010823,"owners_count":21998993,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","keyboard","keyboard-layout","keyboard-mapping","keyboard-remap","keymap","linux","sway","x11"],"created_at":"2024-07-31T22:00:49.364Z","updated_at":"2025-05-13T19:10:59.989Z","avatar_url":"https://github.com/rvaiya.png","language":"C","readme":"[![Kofi](https://badgen.net/badge/icon/kofi?icon=kofi\u0026label)](https://ko-fi.com/rvaiya)\n\n# Impetus\n\n[![Packaging status](https://repology.org/badge/tiny-repos/keyd.svg)](https://repology.org/project/keyd/versions)\n\nLinux lacks a good key remapping solution. In order to achieve satisfactory\nresults a medley of tools need to be employed (e.g xcape, xmodmap) with the end\nresult often being tethered to a specified environment (X11). keyd attempts to\nsolve this problem by providing a flexible system wide daemon which remaps keys\nusing kernel level input primitives (evdev, uinput).\n\n# Note on v2\n\nThe config format has undergone several iterations since the first\nrelease. For those migrating their configs from v1 it is best\nto reread the [man page](https://raw.githubusercontent.com/rvaiya/keyd/refs/heads/master/docs/keyd.scdoc) (`man keyd`).\n\nSee also: [changelog](docs/CHANGELOG.md).\n\n# Goals\n\n  - Speed       (a hand tuned input loop written in C that takes \u003c\u003c1ms)\n  - Simplicity  (a [config format](#sample-config) that is intuitive)\n  - Consistency (modifiers that [play nicely with layers](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128) by default)\n  - Modularity  (a UNIXy core extensible through the use of an [IPC](https://github.com/rvaiya/keyd/blob/90973686723522c2e44d8e90bb3508a6da625a20/docs/keyd.scdoc#L391) mechanism)\n\n# Features\n\nkeyd has several unique features many of which are traditionally only\nfound in custom keyboard firmware like [QMK](https://github.com/qmk/qmk_firmware)\nas well as some which are unique to keyd.\n\nSome of the more interesting ones include:\n\n- Layers (with support for [hybrid modifiers](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128)).\n- Key overloading (different behaviour on tap/hold).\n- Keyboard specific configuration.\n- Instantaneous remapping (no more flashing :)).\n- A client-server model that facilitates scripting and display server agnostic application remapping. (Currently ships with support for X, sway, and gnome (wayland)).\n- System wide config (works in a VT).\n- First class support for modifier overloading.\n- Unicode support.\n\n### keyd is for people who:\n\n - Would like to experiment with custom [layers](https://docs.qmk.fm/feature_layers) (i.e custom shift keys)\n   and oneshot modifiers.\n - Want to have multiple keyboards with different layouts on the same machine.\n - Want to be able to remap `C-1` without breaking modifier semantics.\n - Want a keyboard config format which is easy to grok.\n - Like tiny daemons that adhere to the Unix philosophy.\n - Want to put the control and escape keys where God intended.\n - Wish to be able to switch to a VT to debug something without breaking their keymap.\n\n### What keyd isn't:\n\n - A tool for programming individual key up/down events.\n\n# Dependencies\n\n - Your favourite C compiler\n - Linux kernel headers (already present on most systems)\n\n## Optional\n\n - python      (for application specific remapping)\n - python-xlib (only for X support)\n - dbus-python (only for KDE support)\n\n# Installation\n\n*Note:* master serves as the development branch, things may occasionally break\nbetween releases. Releases are [tagged](https://github.com/rvaiya/keyd/tags), and should be considered stable.\n\n## From Source\n\n    git clone https://github.com/rvaiya/keyd\n    cd keyd\n    make \u0026\u0026 sudo make install\n    sudo systemctl enable --now keyd\n\n# Quickstart\n\n1. Install and start keyd (e.g `sudo systemctl enable keyd --now`)\n\n2. Put the following in `/etc/keyd/default.conf`:\n\n```\n[ids]\n\n*\n\n[main]\n\n# Maps capslock to escape when pressed and control when held.\ncapslock = overload(control, esc)\n\n# Remaps the escape key to capslock\nesc = capslock\n```\n\nKey names can be obtained by using the `keyd monitor` command. Note that while keyd is running, the output of this\ncommand will correspond to keyd's output. The original input events can be seen by first stopping keyd and then\nrunning the command. See the man page for more details.\n\n3. Run `sudo keyd reload` to reload the config set.\n\n4. See the man page (`man keyd`) for a more comprehensive description.\n\nConfig errors will appear in the log output and can be accessed in the usual\nway using your system's service manager (e.g `sudo journalctl -eu keyd`).\n\n*Note*: It is possible to render your machine unusable with a bad config file.\nShould you find yourself in this position, the special key sequence\n`backspace+escape+enter` should cause keyd to terminate.\n\nSome mice (e.g the Logitech MX Master) are capable of emitting keys and\nare consequently matched by the wildcard id. It may be necessary to\nexplicitly blacklist these.\n\n## Application Specific Remapping (experimental)\n\n- Add yourself to the keyd group:\n\n\t`usermod -aG keyd \u003cuser\u003e`\n\n- Populate `~/.config/keyd/app.conf`:\n\nE.G\n\n\t[alacritty]\n\n\talt.] = macro(C-g n)\n\talt.[ = macro(C-g p)\n\n\t[chromium]\n\n\talt.[ = C-S-tab\n\talt.] = macro(C-tab)\n\n- Run:\n\n\t`keyd-application-mapper`\n\nYou will probably want to put `keyd-application-mapper -d` somewhere in your \ndisplay server initialization logic (e.g ~/.xinitrc) unless you are running Gnome.\n\nSee the man page for more details.\n\n## SBC support\n\nExperimental support for single board computers (SBCs) via usb-gadget\nhas been added courtesy of Giorgi Chavchanidze.\n\nSee [usb-gadget.md](src/vkbd/usb-gadget.md) for details.\n\n## Packages\n\nThird party packages for the some distributions also exist. If you wish to add\nyours to the list please file a PR. These are kindly maintained by community\nmembers, no personal responsibility is taken for them.\n\n### Alpine Linux\n\n[keyd](https://pkgs.alpinelinux.org/packages?name=keyd) package maintained by [@jirutka](https://github.com/jirutka).\n\n### Arch\n\n[Arch Linux](https://archlinux.org/packages/extra/x86_64/keyd/) package maintained by Arch packagers.\n\n### Debian\n\nExperimental `keyd` and `keyd-application-mapper` packages can be found in the\nCI build artifacts of the [work-in-progress Debian package\nrepository](https://salsa.debian.org/rhansen/keyd):\n\n  * [amd64 (64-bit)](https://salsa.debian.org/rhansen/keyd/-/jobs/artifacts/debian/latest/browse/debian/output?job=build)\n  * [i386 (32-bit)](https://salsa.debian.org/rhansen/keyd/-/jobs/artifacts/debian/latest/browse/debian/output?job=build%20i386)\n\nAny Debian Developer who is willing to review the debianization effort and\nsponsor its upload is encouraged to contact\n[@rhansen](https://github.com/rhansen) (also see the [Debian ITP\nbug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1060023)).\n\n### Fedora\n\n[COPR](https://copr.fedorainfracloud.org/coprs/alternateved/keyd/) package maintained by [@alternateved](https://github.com/alternateved).\n\n### Gentoo\n\n[GURU](https://gitweb.gentoo.org/repo/proj/guru.git/tree/app-misc/keyd) package maintained by [jack@pngu.org](mailto:jack@pngu.org)\n\n### openSUSE\n[opensuse](https://software.opensuse.org//download.html?project=hardware\u0026package=keyd) package maintained by [@bubbleguuum](https://github.com/bubbleguuum).\n\nEasy install with `sudo zypper in keyd`.\n\n### Ubuntu\n\nExperimental `keyd` and `keyd-application-mapper` packages can be found in the\n[`ppa:keyd-team/ppa`\narchive](https://launchpad.net/~keyd-team/+archive/ubuntu/ppa).\n\nIf you wish to help maintain this PPA, please contact\n[@rhansen](https://github.com/rhansen).\n\n# Example 1\n\n\t[ids]\n\n\t*\n\t\n\t[main]\n\n\tleftshift = oneshot(shift)\n\tcapslock = overload(symbols, esc)\n\n\t[symbols]\n\n\td = ~\n\tf = /\n\t...\n\n# Example 2\n\nThis overrides specific alt combinations macOS users might\nbe more familiar with, while keeping the rest intact.\n\n\t[ids]\n\t*\n\n\t[alt]\n\n\tx = C-x\n\tc = C-c\n\tv = C-v\n\n\ta = C-a\n\tf = C-f\n\tr = C-r\n\tz = C-z\n\n# Recommended config\n\nMany users will probably not be interested in taking full advantage of keyd.\nFor those who seek simple quality of life improvements I can recommend the\nfollowing config:\n\n\t[ids]\n\n\t*\n\n\t[main]\n\n\tshift = oneshot(shift)\n\tmeta = oneshot(meta)\n\tcontrol = oneshot(control)\n\n\tleftalt = oneshot(alt)\n\trightalt = oneshot(altgr)\n\n\tcapslock = overload(control, esc)\n\tinsert = S-insert\n\nThis overloads the capslock key to function as both escape (when tapped) and\ncontrol (when held) and remaps all modifiers to 'oneshot' keys. Thus to produce\nthe letter A you can now simply tap shift and then a instead of having to hold\nit. Finally it remaps insert to S-insert (paste on X11).\n\n# FAQS\n\n## Why is my trackpad is interfering with input after enabling keyd?\n\nlibinput, a higher level input component used by most wayland and X11 setups,\nincludes a feature called 'disable-while-typing' that disables the trackpad\nwhen typing.\n\nIn order to achieve this, it needs to distinguish between internal and external\nkeyboards, which it does by hard coding a rules for specific hardware\n('quirks'). Since keyd creates a virtual device which subsumes both external\nand integrated keyboards, you will need to instruct libinput to regard the keyd\nvirtual device as internal.\n\nThis can be achieved by adding the following to `/etc/libinput/local-overrides.quirks` (which may need to be created):\n\n```\n[Serial Keyboards]\n\nMatchUdevType=keyboard\nMatchName=keyd*keyboard\nAttrKeyboardIntegration=internal\n```\n\nCredit to @mark-herbert42 and @canadaduane for the original solution.\n\n## What about xmodmap/setxkbmap/*?\n\nxmodmap and friends are display server level tools with limited functionality.\nkeyd is a system level solution which implements advanced features like\nlayering and [oneshot](https://docs.qmk.fm/#/one_shot_keys)\nmodifiers.  While some X tools offer similar functionality I am not aware of\nanything that is as flexible as keyd.\n\n## What about [kmonad](https://github.com/kmonad/kmonad)?\n\nkeyd was written several years ago to allow me to easily experiment with\ndifferent layouts on my growing keyboard collection. At the time kmonad did not\nexist and custom keyboard firmware like\n[QMK](https://github.com/qmk/qmk_firmware) (which inspired keyd) was the only\nway to get comparable features. I became aware of kmonad after having published\nkeyd. While kmonad is a fine project with similar goals, it takes a different\napproach and has a different design philosophy.\n\nNotably keyd was written entirely in C with performance and simplicitly in\nmind and will likely never be as configurable as kmonad (which is extensible\nin Haskell). Having said that, it supplies (in the author's opinion) the\nmost valuable features in less than 2000 lines of C while providing\na simple language agnostic config format.\n\n## Why doesn't keyd implement feature X?\n\nIf you feel something is missing or find a bug you are welcome to file an issue\non github. keyd has a minimalist (but sane) design philosophy which\nintentionally omits certain features (e.g execing arbitrary executables\nas root). Things which already exist in custom keyboard firmware like QMK are\ngood candidates for inclusion.\n\n# Contributing\n\nSee [CONTRIBUTING](CONTRIBUTING.md).\nIRC Channel: #keyd on oftc\n","funding_links":["https://ko-fi.com/rvaiya"],"categories":["C","Key Binding Management","WYSIWYG Editors","c","Linux"],"sub_categories":["Other"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frvaiya%2Fkeyd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frvaiya%2Fkeyd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frvaiya%2Fkeyd/lists"}