linux-driver
Apply the Linux driver's LuaJIT, evdev, ydotool, and tap-hold engine invariants. Use when writing, editing, or reviewing the Linux driver.
SKILL.md.claude/skills/linux-driver/SKILL.md
GitHubLinux driver foot-guns
Universal code rules live in AGENTS.md; the strict convention lint is the
formatting authority. This file covers what has actually gone wrong, or is
provably wrong today, in the Linux driver.
Rewritten 2026-08-06. Every technical section of the previous version described a defect that had since been fixed — the grab, the dead evdev decoder, the missing ShellRunner, the race test's apostrophe hole, kanata's device flag. A skill is loaded automatically and read as current, so a stale one is worse than none: it sends the next reader to repair code that is already correct, and its warnings argue against decisions the driver has since made deliberately. Verify before you trust anything here, and rewrite it when you find it wrong.
What still holds
CI runs LuaJIT and exercises both event backends
npm run test:linux probes luajit, then lua5.4, then lua. Develop against
5.4 locally and you are not testing what gates the merge.
utf8is absent under LuaJIT.tests/run.luainstallscompat.utf8before any test module loads. Under 5.4 the shim is redundant, so a module that depends on its exact shape breaks only on LuaJIT.- No bitwise operators. LuaJIT is 5.1-based;
&,<<and//are 5.3+.device_finder.luaspells the EV_KEY bit test out arithmetically for exactly this reason. A&compiles fine on 5.4 and is a syntax error in CI. os.executereturn type. 5.1/LuaJIT return a number, 5.2+ returntrue. Every call site must accept both (result == true or result == 0).- The unit lane installs
luvand admits its real event-loop and file-event integrations. Polling tests explicitly load the dependency as absent, so installed libraries cannot silently change the branch under test.lfsremains optional, so test discovery can still shell out. - Plain
lua5.1is not viable:gotois 5.2+.
A local declared after the function that reads it is a nil global
The single most repeated defect in this driver — five occurrences, two of them on 2026-08-06 alone. The function binds the nil GLOBAL instead of the local, and the read silently does nothing: no error, no log, just a counter that stays at zero or a state that never applies.
Declare module state in the state section at the top, above every reader. This
has its own entry in docs/memory/linux-web-release.md
(project-lua-closure-before-local-nil-global).
A value must be named at EVERY boundary it crosses
Nine defects in one session had one shape: a value computed correctly and lost
at a boundary that drops whatever it does not name by hand — the writer's
allowed set, get_app_stats's projection, the reader's code-to-table map, an
i18n envelope. Nothing errors; the symptom is a panel of zeroes, which reads as
"nobody uses this feature".
When adding a value that must reach the database or a page, grep the whole path for anything that ENUMERATES fields and add it to every one. Then test the join, not the units: this driver has shipped a walk and a writer that were each correct in isolation while the flush called neither.
Writing a table nobody reads is the same blank panel as not writing it
Both halves land in the same change, or the second half looks like the first
half not working. The same rule applies to adapters: adapters/notifier.lua was
deleted once under ADR-008 for having no callers — the file made the port matrix
answer "does Linux notify?" affirmatively by inspection while the practical
answer was no.
Hardware is still unverified in CI
The Linux e2e job is stubbed — no real evdev, no real ydotool. EVIOCGRAB and a
ydotool injection have never run in this repo's CI. Treat every runtime claim as
verified by reading, and validate on real hardware before shipping.
tests/hardware/ exists for exactly this and is the right home for anything a
runner cannot answer.
What was fixed, so you do not go looking
- The grab.
--grabis now the DEFAULT (opts.grab = true);--no-grabis the escape hatch.get_mode()returns"intercept"in production. The old warning that turning it on "makes normal typing vanish entirely" is obsolete — the pass-through was built. - The evdev struct decoder.
M.new,parse_eventand the byte-order helpers were dead code with a test that asserted nothing. Both are gone;input_readernow exportsget_layoutsandresolve_charonly. adapters/shell_runner.luaexists. New shell-outs go through it. There are still ~150 directio.popen/os.executesites outside it; migrating one is welcome, re-deriving quoting at a new site is not.- The race test's apostrophe hole. It has a case named "types an apostrophe like any other character".
- kanata is gone (2026-09-24). The tap-holds and the navigation layer
used to run in kanata, which needed a newer glibc than Debian 12 and Ubuntu
22.04 ship, was never started by the daemon, and broke its whole config on
the first free-text action. Its generator, golden file,
kanata.kbd, the kanata submenu and the parity gate are deleted.device_finderno longer prefers a remap daemon's output; it still drops/devices/virtual/so the daemon cannot read its own uinput device back.
Tap-holds run in the daemon (platform/remap/)
tap_hold_engine.luais pure: evdev events in, events out, with the Windows semantics (hold taken at key-down; a tap only within the key's threshold, no sooner than the minimum tap duration, with no other key pressed, repeated or released, no click and no wheel in between). Keep it free of I/O so it stays testable. Time reaches it only throughtick(now): RCtrl's one-shot Shift is held only past its threshold, as on Windows, so the keyboard hook ticks it before each key event, at that event's stamp, and from its pump once every queued event is dispatched, on an estimate of the events' clock that must never run ahead (the kernel stamps on the wall clock, and without luv the daemon's clock counts whole seconds). While a key holds the layer no other key is a tap-hold, as no Windows one is: each is the layer's key, itself, or nothing for LAlt tapping Backspace. Per-key Windows rules (a tap with no hold, the Backspace logic of LAlt and RCtrl) are tables in the engine, each citing its.ahkblock. The minimum tap duration applies to every tap that waits for its release; Windows checks it only for LShift, LCtrl, RShift, CapsLock holding the layer and LAlt holding it with a tap other than Backspace. That difference is known and not yet decided: do not copy either side to the other without the maintainer.tap_hold_loader.lualays the user'stap_hold.tomlover_shared/tap_hold/defaults.tomlkey by key and field by field, but only when the file saysinherit_defaults = true; otherwise it starts from no keys, so an empty file is the keyboard's own behaviour. A hold modifier drops the default layer and the reverse;tap_action = ""is the native key and"none"swallows it; a malformed user file is reported, never half-applied.tap_hold_writer.luawrites only the keys the user changed, through the shared TOML codec, via temp file then rename, and refuses to overwrite a file that does not parse. Then it reloads the manager. The section-wide restore and clear are not writer commands:infra/tap_hold_scope.luarenders them throughrender_scope()(the preset written explicitly, never inherited) and publishes both files in the shared scope transaction.tap_hold_manager.luais the single owner of "is a tap-hold active": the feature switch, the file'senabledflag and the daemon's pause meet in one place. It installs the engine only throughkeyboard_hook.set_remapper(), which releases everything the previous engine held before swapping — so switching off, pausing, reloading or stopping while CapsLock is down cannot leave Ctrl pressed. Never hand the hook an engine any other way.