y3owk1n/neru v1.53.0

on GitHub

1.53.0 (2026-09-08)

Overview

Linux Wayland is the headline: GNOME and COSMIC are supported, and mode activation is instant on every Wayland desktop through a keyboard proxy that lives as long as the daemon. Elsewhere, a held movement key glides the cursor instead of stepping it, modes can be declared in config, and one curl or irm command installs, updates or removes Neru on every platform.

Migration Guide

A held relative-move key glides instead of stepping
With held_repeat.enabled = true, a held move_mouse_relative binding moves continuously at its step per interval_ms (default 10px / 50ms, 200px/s) instead of firing the step on each interval. Distance per second is unchanged. accel_enabled, accel_ramp_ms and accel_max_multiplier keep their names and shape the glide's speed. initial_delay_ms does not apply to a gliding key. The stepped behaviour cannot be kept except by turning held_repeat off, which also stops scroll and page repeat.

Wayland holds the keyboards for the daemon's lifetime
Neru grabs every physical keyboard at launch and re-emits it through one uinput device, neru-keyboard-proxy.

• It needs a writable /dev/uinput, the same udev rule scroll injection and neru key already need. Without it, modes fall back to overlay keyboard focus as before.
• The compositor sees neru-keyboard-proxy in place of the physical keyboards. Per-device compositor settings (a Sway or Hyprland input block, a per-device layout in KDE) must target that device.
• kanata and keyd work in front of the proxy and across a remapper restart. keyd and kanata --nodelay still have to start before Neru. See docs/LINUX_SETUP.md.

A held global hotkey fires once on Windows
Global hotkeys register with MOD_NOREPEAT. Holding a chord that is not held-repeatable, such as a mode toggle, fires it once instead of at the OS autorepeat rate, as on macOS and Linux.

Cursor & Hotkeys

• Held-key glide: the cursor starts moving on key down, with a subpixel position on a 10ms tick. Two held keys move diagonally at the same speed as one, opposite keys cancel, a short tap travels one step, the glide crosses monitors, and a click fired mid-glide lands where the cursor is. macOS, X11, wlroots, KDE and Windows
• Held global hotkeys repeat on Linux and Windows: with [held_repeat] on, a held [hotkeys] chord bound to scroll, page, relative move or cell move repeats with acceleration, as on macOS. The held_repeat.* options were declared for both platforms and did nothing. In-mode held repeat on X11 no longer stops after its first tick
• Sticky modifiers apply to scroll: a tapped ctrl followed by a scroll key sends ctrl+scroll, and a sticky shift scrolls horizontally where the application maps it so. Before, the indicator lit and the scroll went out unmodified
• A click in grid or recursive grid after a held-key glide lands where the cursor is, not on the selected cell

Modes

• Declared modes: a [modes.<name>] table defines a mode with no logic of its own. It captures the keyboard, shows the indicator text given in the declaration, and answers every key from its own hotkey table. Use it as a layer behind one leader chord: a set of macros on global chords becomes bare letters, with the layer's name on screen. Declared modes enter and leave like built-in ones (neru mode <name>, --toggle, macros, per-app overrides), a step can hand off into scroll or hints, Escape = "idle" is bound by default, and neru status reports them by name

[modes.window]
indicator = "Window"

[modes.window.hotkeys]
"h" = "exec yabai -m window --focus west"
"f" = ["exec yabai -m window --toggle zoom-fullscreen", "idle"]
"s" = "scroll"

Install

• One-command installer: curl -fsSL .../scripts/install.sh | bash on macOS and Linux, irm .../scripts/install.ps1 | iex on Windows. It downloads the release, verifies the checksum, and installs the app or binary, man pages, shell completions and login service. Running it again updates in place. --channel nightly or --version vX.Y.Z picks a build, --uninstall removes, --purge also deletes config after asking. just install uses the same script. The per-platform install and uninstall scripts are removed
• The PowerShell installer keeps its window open and respects the execution policy. The shell installer detects a Nix-managed launch agent and removes the systemd unit the old installer wrote

Linux

• GNOME Wayland. Mutter implements none of the wlr protocols, so the wayland-gnome backend uses libei via the RemoteDesktop portal for input, the ScreenCast portal for capture, the X11 overlay on Xwayland, and a GNOME Shell extension Neru installs itself for the focused window. Xwayland is required. docs/LINUX_DESKTOPS.md has the protocol table and the HiDPI caveat
• COSMIC. A COSMIC session used to resolve to wayland-other and refuse to start. It runs as wayland-cosmic with hints, grid, scroll, global hotkeys, per-app config and window-relative hint correction. Pointer input needs xdg-desktop-portal-cosmic 1.7 or later
• Instant mode activation: the lifetime proxy makes key capture a routing switch. Before, a mode waited for the activation chord to be released and accepted input up to six hundred milliseconds after the overlay appeared, with keys typed in that window reaching the focused app
• Key remappers: kanata and keyd work in front of the proxy and survive a restart under a running daemon. If a remapper auto-detects and grabs the proxy, it fails open within a third of a second, so the keyboard never goes dead
• Compositor-launched modes no longer stick a modifier: the proxy grabs a keyboard only once every key on it is up, so a mode bound in Hyprland or KDE no longer leaves Super held
• A Super+; chord no longer opens the launcher on KWin, Mutter or a Hyprland bindr
• Shift+Tab, PageUp, PageDown and non-us symbols bind: keys are named by the character they type, so the default Shift+Tab hint binding fires on every backend and one binding matches on Wayland and X11 on any layout. Delete binds to the backspace key, as on macOS and Windows
• labwc, the generic wlroots desktop tag, and Bluetooth keyboards that expose a volume axis are recognised
• KDE: screen-capture streams with no position are placed, and the focused window stays current after the tray closes its bus connection. wlroots: windows already open at startup are tracked. X11: hints target the focused window rather than a Chromium frame, and scroll rounds to the nearest notch instead of truncating
• passthrough_unbounded_keys warns once at load on X11, where it cannot work, and neru doctor says why. Launch-time config warnings are logged, not only on hot reload

Windows

• Injected clicks and drags carry the action's modifiers
• Keys are dispatched off the low-level hook thread, as on the other platforms, and a stopped keyboard hook's WM_QUIT no longer reaches other message pumps
• Grid cells no longer reappear behind an open subgrid
• neru docs opens the documentation

Hints

• The contour strategy asks for screen-capture consent on its first activation. It works on KDE Plasma and reports a missing Screen Recording permission on macOS, instead of failing with a consent error nothing had prompted for

Features

• hotkeys: glide the cursor smoothly while a relative-move key is held (#1626) (89b6f1c)
• hotkeys: repeat a held global hotkey on Linux and Windows (#1621) (19b40a3)
• install: install, update and remove Neru with one curl or irm command (#1630) (30fc7f5)
• linux: make Wayland mode activation instant with a lifetime keyboard proxy (#1600) (52fa240)
• linux: support cosmic desktop (#1636) (f65d3a4)
• linux: support gnome wayland (#1638) (7e3290b)
• modes: add support for user declared custom mode (#1629) (3a3ee0e)

Bug Fixes

• cli: open the docs on Windows, where the tray already knows how (#1620) (16a3c90)
• hints: ask for screen-capture consent before the contour strategy runs (#1596) (71d1b34)
• hotkeys: bind Delete to the backspace key on Linux, as on macOS and Windows (#1624) (2cbe3ce)
• install: keep the PowerShell window open and respect the execution policy (#1631) (ed79130)
• install: notice Nix launch agents and clean up the old installer's systemd unit (#1632) (212a7d1)
• linux: capture Bluetooth keyboards that expose a volume axis (#1633) (90f1447)
• linux: keep the kde focused window current after the tray closes the bus (#1642) (e092e6d)
• linux: keep the Wayland keyboard alive when a remapper grabs Neru's proxy or starts after it (#1604) (1e8e7da)
• linux: keep Wayland hotkeys working with a key remapper across its restarts (#1602) (cffb996)
• linux: name keys by the character they type so Shift+Tab and PageUp bindings fire (#1599) (1516fb7)
• linux: pick the x11-focused window for hints instead of a chromium frame (#1645) (3029791)
• linux: place KDE screen-capture streams that carry no position (#1635) (66f2f45)
• linux: recognize labwc and the wlroots desktop tag (#1637) (61844b7)
• linux: release forwarded keys on the proxy keyboard when it fails open (#1619) (00715b3)
• linux: round a scroll to the nearest notch instead of truncating it (#1618) (ad4dc5c)
• linux: stop a mod hotkey chord opening the desktop launcher on Wayland (#1634) (cdc0a1e)
• linux: stop a modifier sticking after a Wayland mode launched from a compositor binding (#1603) (7831a5b)
• linux: track windows already open when neru starts on wlroots (#1643) (88463d4)
• linux: warn once when passthrough_unbounded_keys is set on the X11 backend (#1625) (4e6659f)
• modes: click where a held-key glide left the cursor, not on the grid selection (#1627) (3655957)
• scroll: apply a sticky modifier to scroll actions (#1615) (2eb92ff)
• windows: carry the action's modifiers on injected clicks and drags (#1614) (c331fa2)
• windows: dispatch keys off the low-level hook thread, as the other taps do (#1617) (f151a66)
• windows: keep a stopped keyboard hook's WM_QUIT off other message pumps (#1598) (73730a9)
• windows: stop the grid cells reappearing behind an open subgrid (#1622) (4c8268c)