{"id":50384539,"url":"https://github.com/nitive/kmap","last_synced_at":"2026-05-30T14:01:35.166Z","repository":{"id":346000777,"uuid":"1187978123","full_name":"Nitive/kmap","owner":"Nitive","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-21T19:04:33.000Z","size":165,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T08:37:00.440Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nitive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-21T13:02:36.000Z","updated_at":"2026-03-21T19:04:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Nitive/kmap","commit_stats":null,"previous_names":["nitive/kmap"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Nitive/kmap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitive%2Fkmap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitive%2Fkmap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitive%2Fkmap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitive%2Fkmap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nitive","download_url":"https://codeload.github.com/Nitive/kmap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitive%2Fkmap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33694714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2026-05-30T14:01:32.118Z","updated_at":"2026-05-30T14:01:35.152Z","avatar_url":"https://github.com/Nitive.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kmap\n\n`kmap` is a low-level Linux keyboard remapper written in Go.\n\nIt reads events from one or more real keyboard devices, applies mapping rules from YAML, and emits remapped key events through a virtual keyboard on `/dev/uinput`.\n\n## Quick Start\n\n1. Build the binary:\n\n```bash\nmake build\n```\n\n2. Install the active config at `/etc/kmap/kmap.yaml`:\n\n```bash\nsudo install -d /etc/kmap\nsudo install -m 644 ./kmap.yaml /etc/kmap/kmap.yaml\n```\n\n3. Edit `/etc/kmap/kmap.yaml` for your machine:\n   - set `devices:` if you want anything other than the built-in default device path\n   - adjust `shortcut_layout`, `tap_layout_switches`, and `mappings`\n\n4. Validate the config:\n\n```bash\n./bin/kmap validate-config\n```\n\n5. Start the daemon:\n\n```bash\n./bin/kmap start\n```\n\n`kmap start` automatically generates `~/.XCompose` before the daemon begins remapping, so `to_symbol` mappings stay aligned with the running config.\n\n## Requirements\n\n- Linux with access to `/dev/input/...` keyboard devices\n- access to `/dev/uinput`\n- if you use `shortcut_layout` or `tap_layout_switches`, KDE with `qdbus6`\n\nIf you run `kmap` as an unprivileged user, that user must have permission to read the input devices and open `/dev/uinput`.\n\n## Config\n\nThe default config path is:\n\n```text\n/etc/kmap/kmap.yaml\n```\n\nYou can override it with `--config \u003cpath\u003e` on any command.\n\nThe repository root [`kmap.yaml`](./kmap.yaml) is an example config you can copy and adapt.\n\n### Device Selection\n\n`devices:` accepts one or more `/dev/input/...` paths. Good stable choices are usually under `/dev/input/by-id/` or `/dev/input/by-path/`.\n\nIf `devices:` is omitted, `kmap` falls back to the built-in default path:\n\n```text\n/dev/input/by-path/platform-i8042-serio-0-event-kbd\n```\n\n### Mapping Actions\n\nEach mapping supports exactly one action:\n\n- `passthrough: true`\n- `pause: true`\n- `to_symbol: …`\n- `to_keys: [...]`\n- `to_chord: Ctrl-Shift-X`\n\nBindings support exact modifier combinations, including combinations such as `Ctrl-Alt-Shift-Meta-K`.\n\n### Pause Safety Switch\n\nYou can define a hotkey that pauses remapping and releases input grabs. While paused, physical keyboards pass through directly. Press the same hotkey again to resume.\n\nExample:\n\n```yaml\nmappings:\n  Caps-Backspace:\n    pause: true\n```\n\nThis is intended as a safety mechanism if a bad mapping leaves the daemon in an unusable state.\n\n## Commands\n\n```bash\nkmap start [--config /etc/kmap/kmap.yaml] [--device /dev/input/...]\nkmap generate-xcompose --output ~/.XCompose [--config /etc/kmap/kmap.yaml]\nkmap validate-config [--config /etc/kmap/kmap.yaml]\n```\n\nRun help for details:\n\n```bash\nkmap \u003ccommand\u003e -h\n```\n\n## Systemd User Service\n\nThe repository includes a generic user service in [`services/kmap.service`](./services/kmap.service).\n\nInstall it with:\n\n```bash\nmake install\n```\n\nThis installs:\n\n- `~/.local/bin/kmap`\n- `~/.config/systemd/user/kmap.service`\n\nand enables the service with `systemctl --user`.\n\nUseful targets:\n\n```bash\nmake restart\nmake uninstall\n```\n\n## How It Works\n\nWhen you run `kmap start`, the app does this:\n\n1. Load `/etc/kmap/kmap.yaml` by default.\n2. Generate `~/.XCompose` from all configured `to_symbol` mappings.\n3. Resolve input devices from `--device`, `devices:`, or the built-in default device path.\n4. Start one independent input pipeline per device.\n5. Watch unavailable devices and capture them when they appear.\n\nEach pipeline uses:\n\n- `pkg/daemon/input`: read Linux input events and manage EVIOCGRAB\n- `pkg/daemon/mapper`: apply remapping, compose emission, and pause toggle detection\n- `pkg/daemon/output`: send remapped events through a virtual keyboard\n- `pkg/daemon/shortcut`: optional KDE shortcut layout switching\n\n## Layout Switching\n\nIf `shortcut_layout` is configured, `kmap` validates that the target layout exists in KDE and temporarily switches to that layout while shortcut modifiers are held. This keeps shortcuts stable even when your typing layout is different.\n\n`tap_layout_switches` can also assign tap-only actions to `LAlt`, `RAlt`, and `Caps`.\n\n## Development\n\n```bash\nmake build\nmake test\nmake lint\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitive%2Fkmap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnitive%2Fkmap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitive%2Fkmap/lists"}