https://github.com/rvaiya/keyd Skip to content Toggle navigation Sign up * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code Explore + All features + Documentation + GitHub Skills + Blog * Solutions For + Enterprise + Teams + Startups + Education By Solution + CI/CD & Automation + DevOps + DevSecOps Case Studies + Customer Stories + Resources * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Pricing [ ] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this user All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} rvaiya / keyd Public * Notifications * Fork 82 * Star 1.3k A key remapping daemon for linux. License MIT license 1.3k stars 82 forks Star Notifications * Code * Issues 32 * Pull requests 7 * Actions * Projects 0 * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Security * Insights rvaiya/keyd This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. master Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags Name already in use A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? Cancel Create 4 branches 20 tags Code * Local * Codespaces * Clone HTTPS GitHub CLI [https://github.com/r] Use Git or checkout with SVN using the web URL. [gh repo clone rvaiya] Work fast with our official CLI. Learn more about the CLI. * Open with GitHub Desktop * Download ZIP Sign In Required Please sign in to use Codespaces. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching Xcode If nothing happens, download Xcode and try again. Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit Git stats * 417 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time data docs examples layouts scripts src t .gitattributes .gitignore CONTRIBUTING.md LICENSE Makefile README.md TODO keyd.service View code [ ] Impetus Note on v2 Goals Features keyd is for people who: What keyd isn't: Dependencies Optional Installation From Source Quickstart Application Specific Remapping (experimental) SBC support Packages Alpine Linux Arch Sample Config Recommended config FAQS What about xmodmap/setxkbmap/*? What about kmonad? Why doesn't keyd implement feature X? Contributing README.md Kofi Impetus Packaging status Linux lacks a good key remapping solution. In order to achieve satisfactory results a medley of tools need to be employed (e.g xcape, xmodmap) with the end result often being tethered to a specified environment (X11). keyd attempts to solve this problem by providing a flexible system wide daemon which remaps keys using kernel level input primitives (evdev, uinput). Note on v2 The config format has undergone several iterations since the first release. For those migrating their configs from v1 it is best to reread the man page. See also: changelog. Goals * Speed (a hand tuned input loop written in C that takes <<1ms) * Simplicity (a config format that is intuitive) * Consistency (modifiers that play nicely with layers by default) * Modularity (a UNIXy core extensible through the use of an IPC mechanism) Features keyd has several unique features many of which are traditionally only found in custom keyboard firmware like QMK as well as some which are unique to keyd. Some of the more interesting ones include: * Layers (with support for hybrid modifiers). * Key overloading (different behaviour on tap/hold). * Keyboard specific configuration. * Instantaneous remapping (no more flashing :)). * A client-server model that facilitates scripting and display server agnostic application remapping. (Currently ships with support for X, sway, and gnome). * System wide config (works in a VT). * First class support for modifier overloading. * Unicode support. keyd is for people who: * Would like to experiment with custom layers (i.e custom shift keys) and oneshot modifiers. * Want to have multiple keyboards with different layouts on the same machine. * Want to be able to remap C-1 without breaking modifier semantics. * Want a keyboard config format which is easy to grok. * Like tiny daemons that adhere to the Unix philosophy. * Want to put the control and escape keys where God intended. * Wish to be able to switch to a VT to debug something without breaking their keymap. What keyd isn't: * A tool for programming individual key up/down events. Dependencies * Your favourite C compiler * Linux kernel headers (already present on most systems) Optional * python (for application specific remapping) * python-xlib (only for X support) Installation Note: master serves as the development branch, things may occasionally break between releases. Releases are tagged, and should be considered stable. From Source git clone https://github.com/rvaiya/keyd cd keyd make && sudo make install sudo systemctl enable keyd && sudo systemctl start keyd Quickstart 1. Install and start keyd (e.g sudo systemctl enable keyd) 2. Put the following in /etc/keyd/default.conf: [ids] * [main] # Maps capslock to escape when pressed and control when held. capslock = overload(control, esc) # Remaps the escape key to capslock esc = capslock Key names can be obtained by using the keyd monitor command. Note that while keyd is running, the output of this command will correspond to keyd's output. The original input events can be seen by first stopping keyd and then running the command. See the man page for more details. 3. Run sudo keyd reload to reload the config set. 4. See the man page (man keyd) for a more comprehensive description. Config errors will appear in the log output and can be accessed in the usual way using your system's service manager (e.g sudo journalctl -eu keyd). Note: It is possible to render your machine unusable with a bad config file. Should you find yourself in this position, the special key sequence backspace+escape+enter should cause keyd to terminate. Some mice (e.g the Logitech MX Master) are capable of emitting keys and are consequently matched by the wildcard id. It may be necessary to explicitly blacklist these. Application Specific Remapping (experimental) * Add yourself to the keyd group: usermod -aG keyd * Populate ~/.config/keyd/app.conf: E.G [alacritty] alt.] = macro(C-g n) alt.[ = macro(C-g p) [chromium] alt.[ = C-S-tab alt.] = macro(C-tab) * Run: keyd-application-mapper You will probably want to put keyd-application-mapper -d somewhere in your display server initialization logic (e.g ~/.xinitrc) unless you are running Gnome. See the man page for more details. SBC support Experimental support for single board computers (SBCs) via usb-gadget has been added courtesy of Giorgi Chavchanidze. See usb-gadget.md for details. Packages Third party packages for the some distributions also exist. If you wish to add yours to the list please file a PR. These are kindly maintained by community members, no personal responsibility is taken for them. Alpine Linux keyd package maintained by @jirutka. Arch AUR package maintained by eNV25. Sample Config [ids] * [main] leftshift = oneshot(shift) capslock = overload(symbols, esc) [symbols] d = ~ f = / ... Recommended config Many users will probably not be interested in taking full advantage of keyd. For those who seek simple quality of life improvements I can recommend the following config: [ids] * [main] shift = oneshot(shift) meta = oneshot(meta) control = oneshot(control) leftalt = oneshot(alt) rightalt = oneshot(altgr) capslock = overload(control, esc) insert = S-insert This overloads the capslock key to function as both escape (when tapped) and control (when held) and remaps all modifiers to 'oneshot' keys. Thus to produce the letter A you can now simply tap shift and then a instead of having to hold it. Finally it remaps insert to S-insert (paste on X11). FAQS What about xmodmap/setxkbmap/*? xmodmap and friends are display server level tools with limited functionality. keyd is a system level solution which implements advanced features like layering and oneshot modifiers. While some X tools offer similar functionality I am not aware of anything that is as flexible as keyd. What about kmonad? keyd was written several years ago to allow me to easily experiment with different layouts on my growing keyboard collection. At the time kmonad did not exist and custom keyboard firmware like QMK (which inspired keyd) was the only way to get comparable features. I became aware of kmonad after having published keyd. While kmonad is a fine project with similar goals, it takes a different approach and has a different design philosophy. Notably keyd was written entirely in C with performance and simplicitly in mind and will likely never be as configurable as kmonad (which is extensible in Haskell). Having said that, it supplies (in the author's opinion) the most valuable features in less than 2000 lines of C while providing a simple language agnostic config format. Why doesn't keyd implement feature X? If you feel something is missing or find a bug you are welcome to file an issue on github. keyd has a minimalist (but sane) design philosophy which intentionally omits certain features (e.g execing arbitrary executables as root). Things which already exist in custom keyboard firmware like QMK are good candidates for inclusion. Contributing See CONTRIBUTING. IRC Channel: #keyd on oftc About A key remapping daemon for linux. Topics c linux keyboard keyboard-layout x11 keymap sway keyboard-mapping keyboard-remap Resources Readme License MIT license Stars 1.3k stars Watchers 9 watching Forks 82 forks Report repository Releases 2 v2.4.3 Latest May 16, 2023 + 1 release Packages 0 No packages published Contributors 27 * * * * * * * * * * * + 16 contributors Languages * C 85.2% * Python 10.7% * Perl 2.9% * Other 1.2% Footer (c) 2023 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.