{"id":24541511,"url":"https://github.com/samvel1024/kbct","last_synced_at":"2025-10-03T17:31:03.212Z","repository":{"id":37966450,"uuid":"242410098","full_name":"samvel1024/kbct","owner":"samvel1024","description":"Keyboard keycode mapping utility for Linux supporting layered configuration","archived":false,"fork":false,"pushed_at":"2022-10-27T07:52:14.000Z","size":124,"stargazers_count":238,"open_issues_count":25,"forks_count":19,"subscribers_count":3,"default_branch":"master","last_synced_at":"2023-11-07T19:02:48.975Z","etag":null,"topics":["keyboard","keyboard-layout","linux","uinput","xorg"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samvel1024.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-22T20:52:29.000Z","updated_at":"2023-10-25T04:57:48.000Z","dependencies_parsed_at":"2023-01-19T14:46:01.532Z","dependency_job_id":null,"html_url":"https://github.com/samvel1024/kbct","commit_stats":null,"previous_names":[],"tags_count":2,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samvel1024%2Fkbct","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samvel1024%2Fkbct/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samvel1024%2Fkbct/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samvel1024%2Fkbct/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samvel1024","download_url":"https://codeload.github.com/samvel1024/kbct/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235161541,"owners_count":18945540,"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":["keyboard","keyboard-layout","linux","uinput","xorg"],"created_at":"2025-01-22T18:17:53.004Z","updated_at":"2025-10-03T17:30:57.831Z","avatar_url":"https://github.com/samvel1024.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"## \n\n## KBCT - Keyboard Customization Tool for Linux :gear: :computer: :penguin:\n\n![img](https://i.imgur.com/ryVuxe5.jpeg)\n\nKBCT is yet another tool that will help to remap keys across the desktop environment.\n\nWhen is KBCT useful?\n\n- If you want to have a custom **ergonomic keyboard layout** (when your fingers almost never need to leave the home row keys).\n\n- If you're an ex MacOS user and want something similar to [Karabiner Elements](https://github.com/pqrs-org/Karabiner-Elements).\n\n- If you want to achieve something similar to **QMK layers on your laptop keyboard**.\n\n- If you want to have system-wide **vim-like navigation** mapping `some_modifier + hjkl` to arrow keys.\n\n- If you find `xbindkeys` ,`xmodmap` and `setxkbmap` ~~impossible~~ hard to configure.\n\n- If you want your mapping configuration to work on **both Wayland and X11**.\n\n- If you want to remap buttons on your **mouse** or other input devices.\n\n- If you want the configuration to be simple and intuitive.\n\n***However, KBCT is not** a tool that can be used to configure macros or arbitrary command execution on a key press. Also note that **KBCT requires sudo access**.\n\n****KBCT is in active development** so expect to see some bugs, however it should be stable enough for simple use cases. In any case create an issue if you encounter something unexpected.\n\n### \n\n### Installation\n\nThere are several ways of installing KBCT:\n\n- Download the pre-built x86_64 AppImage binary from [releases](https://github.com/samvel1024/kbct/releases):\n\n  ```bash\n  cd ~/Downloads\n  wget https://github.com/samvel1024/kbct/releases/latest/download/kbct-x86_64.AppImage\n  chmod +x kbct-x86_64.AppImage\n\n  #Check that it works\n  sudo ./kbct-x86_64.AppImage list-devices\n  ```\n\n- Compile from the sources by first installing `libudev1` and `libudev-dev` packages (available for all known distributions):\n\n  ```\n  sudo apt install libudev1 \u0026\u0026 \\\n\tsudo apt install libudev-dev  # for ubuntu/debian\n  ```\n\n  Then assuming that you have a [Rust toolchain](https://www.rust-lang.org/tools/install) installed run the following:\n\n  ```bash\n  cd /tmp \u0026\u0026\n  git clone https://github.com/samvel1024/kbct \u0026\u0026 \\\n  cd kbct \u0026\u0026 \\\n  cargo build --release \u0026\u0026 \\\n  ./target/release/kbct --help\n  ```\n\n- Install from the AUR:\n\n  If you are an Arch Linux user, you can install it from\n  [AUR](https://aur.archlinux.org/):\n\n  ```\n  $ yay -S kbct-git\n  ```\n\n  \u003e Note: The configuration file is expected to be in\n  \u003e `/etc/kbct/config.yml`.\n\n\n### Automatic startup\nOn Arch Linux, systemd service file is installed automatically. On other distributions, put this into `/etc/systemd/system/kbct.service`:\n\t\n```\n[Unit]\nDescription=Keyboard keycode mapping daemon supporting layered configuration\n\n[Service]\nType=simple\nExecStartPre=modprobe uinput\nExecStart=/bin/sh -c \"PATH_TO_EXECUTABLE remap --config PATH_TO_CONFIG\"\nRestart=always\n\n[Install]\nWantedBy=default.target\n```\n\nDo not forget to replace PATH_TO_EXECUTABLE and PATH_TO_CONFIG as needed. Then run: \n\n```bash\n$ systemctl daemon-reload\n```\n\n```bash\n$ systemctl start kbct\n```\n\nTo make it run on boot automatically, run:\n```bash\n$ systemctl enable kbct\n```\n\n### \n\n### Configuration\n\nKBCT uses YAML files as configuration. It allows to apply different mapping rules for different keyboards. There are two main types of key mappings\n\n- `keymap`: maps keys 1-1 regardless of any  layer modifiers. (e.g `capslock -\u003e leftctrl`)\n\n- `layers`: maps keys based on the active layer. Layer is a key map that will activate and override the existing mapping if a given set of keys are pressed. Much like `fn` key is combined with `F1-F12` keys. (e.g `rightalt+i=up` or `rightalt+leftctrl+comma=volumeup` )\n\n**The following is an exhaustive example configuration of KBCT**\n\n```yaml\n# Apply this configuration to two keyboards (if connected)\n- keyboards: [ \"Lenovo TrackPoint Keyboard II\", \"AT Translated Set 2 keyboard\"]\n\n  keymap:\n    leftalt: leftctrl\n    capslock: leftalt\n    sysrq: rightmeta\n  # Specify layered configurations (much similar to fn+F keys)\n  layers:\n    # Specify the modifiers of the layer\n    - modifiers: ['rightalt']\n      keymap:\n        i: up\n        j: left\n        k: down\n        l: right\n        u: pageup\n        o: pagedown\n        p: home\n        semicolon: end\n```\n\nAs a result the above configuration will have the following effect\n\n```textile\n# ↓/↑ stand for press/release events\n# One to one example\nleftalt↓ ⟶ leftctrl↓\nleftalt↑ ⟶ leftctrl↑\n\n# Layer example\nrightalt↓ ⟶ rightalt↓\ni↓ ⟶ rightalt↑ up↓\ni↑ ⟶ up↑\nrightalt↑ ⟶ ∅\n```\n\nTo start KBCT based on YAML configuration file run:\n\n```bash\nsudo kbct remap --config ~/.config/kbct.yaml \n```\n\n[Here](https://gist.githubusercontent.com/samvel1024/02e5675e04f9d84f098e98bcd0e1ea12/raw/e18d950ce571b4ff5c832cc06406e9a6afece132/keynames.txt) you can find all the available key names to use in the configuration. Essentially those are taken from Linux API [headers](https://github.com/torvalds/linux/blob/master/include/uapi/linux/input-event-codes.h). In case you want to disable a key map it to `reserved`. For example disabling capslock will look like this `capslock: reserved`.\n\n\n**Hint:**\nTo begin with, you might want to start KBCT in [debugging mode](#troubleshooting), until you arrive at a working configuration.\n\n**Important note:** KBCT is treating `leftshift`/`rightshift` , `leftalt`/`rightalt`, etc. as different keys, so if you want to map both you need to define the mapping twice. This is done on purpose to give fine grained control over configuration.\n\n### Troubleshooting\n**What is the name of my keyboard?**\nIn order to list all the available keyboard devices and their respective names run the following:\n\n```bash\n$ sudo kbct list-devices\n```\n\nMost often a keyboard laptop will be named `AT Translated Set 2 keyboard`. If you're not sure what the name of your keyboard is, run `sudo evtest`, select a device from a list and try typing. If it lets you type without spitting output, you selected a wrong device. Repeat until you see output like this:\n```\nEvent: time 1641154916.130391, -------------- SYN_REPORT ------------\nEvent: time 1641154916.130391, type 4 (EV_MSC), code 4 (MSC_SCAN), value 7004f\nEvent: time 1641154916.130391, type 1 (EV_KEY), code 106 (KEY_RIGHT), value 0\nEvent: time 1641154916.130391, -------------- SYN_REPORT ------------\n```\n\n**What are the names of the keys?**\nKBCT uses the lowest possible level keycodes from the Linux kernel to perform remapping. Window managers/desktop environments may have other namings for the same keys for various reasons. To know the exact name of the key you're interested you can use either `sudo evtest /dev/input/eventXX`, or `sudo kbct log-keys --device-path /dev/input/eventXX` where XX should be replaced by the appropriate device path. Then just type.\n\n**It just does not work**\nTry loading uinput module (KBCT will not function but will not produce an error if the uinput module is not loaded):\n\n```bash\nsudo modprobe uinput\n```\n\nKBCT uses the lowest possible level keycodes from the Linux kernel to perform remapping. Window managers/desktop environments may have other namings for the same keys for various reasons. To know the exact name of the key you're interested you can use either `sudo evtest /dev/input/event\u003ci\u003e`, or `sudo kbct log-keys --device-path /dev/input/event\u003ci\u003e` where `\u003ci\u003e` should be replaced by the appropriate device number. You can then start typing to see the key names.\n\n**Debugging KBCT**\nIn order to start KBCT in debug mode, you may run the following line:\n\n```bash\nsudo RUST_BACKTRACE=1 kbct --debug-log remap --config \u003cCONFIG-PATH\u003e\n```\n\nWhen you now press key combinations, you will see the following pattern: `DEBUG kbct \u003e +KEY_NAME -\u003e +KEY_NAME`. The left hand side of `-\u003e` corresponds to the input that KBCT receives, whereas the right hand side represents what KBCT proxies the current key state to.\n\nThe `+` refers to a **keydown**-event and the `-` refers to a **keyup**-event.\n\n**HINT:** If KBCT behaves erroneously after a config change, it may be worth a try to reload the `uinput` kernel module using `sudo modprobe uinput` before restarting KBCT.\n\n### How it works\n\nKBCT is operating on a low enough level to be independent from the window manager or the desktop environment. It is achieved by the following steps:\n\nSince KBCT should be run as root, it has enough privileges to read and grab the output of a keyboard or another input device (e.g the output of `/dev/input/event2`). Which means that it becomes readable only for KBCT and that the display manager is no longer able to read from that device.\n\nThen KBCT creates another virtual `uinput`device (e.g. `/dev/input/event6`), and sends customized key events to that device. The new mapped keyboard or device is successfully read by the window manager, which as a result reads customized key events.\n\n\n### Examples\n\nSee the [examples.md](./examples.md) for user-submitted kbct remap examples.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamvel1024%2Fkbct","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamvel1024%2Fkbct","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamvel1024%2Fkbct/lists"}