y3owk1n/neru v1.51.0

on GitHub

1.51.0 (2026-08-14)

Overview

Linux is the headline: the vision hint strategy works there now, screen capture landed on X11, wlroots and KDE, neru services manages a real systemd user unit, and notifications go through D-Bus — with overlay parity (search badge, virtual pointer, smooth scroll) across every backend. Everywhere else the theme is no silent no-ops: a mistyped mode flag or a stray argument is refused instead of accepted-and-ignored, every option now declares which platforms actually read it, and the daemon's socket and log are scoped to the user running it. Relative cursor movement finally animates, on macOS and Linux.

Migration Guide

Mistyped and inert mode flags are now errors
A mode command is read the same way whether it is typed, written in a binding, or sent over the socket — and arguments it cannot act on are refused instead of dropped:

neru idle left_click        # was: activated idle, argument ignored
                            # now: unknown command "left_click" for "neru idle"
"hints --serach"            # was: loaded clean, did nothing when pressed
                            # now: reported by `neru config validate`

Run neru config validate after upgrading. An unknown flag or a value no flag can carry fails the load; a flag the named mode simply has no use for (grid --search) is a warning and the rest of your config still loads.

Options that do nothing on this platform now say so at load
Every option, mode flag and action carries a macOS/Linux/Windows column. Writing an inert one is never an error — the file loads, the daemon starts — but it is now reported once at load and listed under platform_support in neru doctor. Nothing to change; one config still works on every machine.

Restart the daemon, and on macOS re-run neru services install
The IPC endpoint moved to a per-user location ($XDG_RUNTIME_DIR/neru/neru.sock, else $TMPDIR/neru-<uid>/neru.sock; a per-SID named pipe on Windows), so a 1.50 daemon and a 1.51 CLI will not find each other. On macOS the daemon's stderr moved out of the shared /tmp to ~/Library/Logs/neru/daemon.err.log — re-running neru services install regenerates the launch agent.

Linux

• Hints from what is actually on screen — hints.strategy = "vision" now works on Linux through tesseract, reading only the focused window. Text-only: rectangle detection stays macOS-only
• Screen capture on every backend — X11 and wlroots read pixels back through the display server; KDE goes through xdg-desktop-portal over PipeWire, with the consent grant persisted so the prompt is paid once. The screen-capture preflight reports the portal's real state instead of always claiming granted
• neru services works on Linux — install, enable and start the daemon as a systemd user unit tied to graphical-session.target, instead of hand-writing one from the setup guide. systemd only; other init systems say so plainly rather than half-working
• Notifications and alerts through freedesktop D-Bus
• Overlay parity across backends — hint search input badge, grid virtual-pointer indicator, animated smooth scroll, corner radius on hint boundaries and recursive-grid labels, and a paused tray icon (plus a clear announcement on a no-CGO build)
• Injected input stops leaking modifiers — X11 clicks and scrolls no longer carry modifiers you are physically holding, and a modifier Neru injects no longer latches as sticky
• KDE/KWin — focused-window bounds reported where the window is now, the remote-desktop grant kept across daemon restarts, the subgrid drawn instead of a stale frame, grid cells no longer reappearing behind it, and the whole subgrid painted in one repaint
• Hyprland picks the active monitor from the physical mouse; a missing font family falls back to the generic one; a failed compositor query is told apart from an unfocused desktop

Configuration & CLI

• Every option, flag and action declares its platforms — generated into the cross-platform table, surfaced in neru doctor, and kept honest by a build failure rather than a review
• neru config validate reads the flags inside your bindings, not just the command word
• neru hints --debug is a read-only probe command of its own — same spelling, same output, but it takes only the flags that decide what gets collected and refuses the rest instead of silently discarding --action
• Insert key in hotkey bindings, on X11 and Windows
• --modifier on scroll actions — bind Shift+scroll or Ctrl+scroll
• Grid labels are validated — a single character, a repeat, or one that cannot be typed leaves cells unreachable and is now reported; the grid is labelled from the characters it is actually built with
• Nix — services.neru.settings writes your TOML config from the module

Cursor & Scroll

• Relative cursor moves animate — hjkl-style movement glides over a fixed per-move duration instead of teleporting, on macOS and now Linux. Speed scales with the delta and composes with held-key acceleration; unchanged unless [smooth_cursor] is enabled
• Scrolls anchor where the cursor is headed during an animated move, and a held scroll key travels exactly as far as the same number of presses

macOS

• Overlays the WindowServer silently pins to one Space are repaired, instead of a mode drawing nothing after a Space change
• Actions land where the cursor is rather than at a point it has already left
• Accessibility priming no longer opens status-bar menus, search_field and switch produce hints, an unmodified scroll no longer inherits held modifiers, numpad Enter matches Return bindings while numpad Clear stops firing delete, and the tree builds on Apple clang 15

Windows

• The daemon survives thousands of mode activations — a leak that eventually took it down
• hints.ui.placement is honoured instead of pinning every label to the element corner, the recursive-grid sub-key preview is drawn the way Linux and macOS draw it, and the font family is resolved once instead of on every label

Reliability & Security

• The IPC endpoint is scoped to one user — an owner-only directory and 0600 socket, a per-SID pipe with a protected descriptor on Windows, and the daemon answers only connections from its own user
• The daemon log is per-user and no longer writes down content — out of shared /tmp, with exec command lines, their output, and config values kept out of it
• Global hotkeys keep working while a mode is active, the keyboard stays captured across a mode-to-mode switch, and a hung app no longer stalls a keystroke inside a mode
• Clean shutdown — no hang on quit during an app switch, and the overlay is released after the event tap
• Release archives carry signed build provenance, third-party CI actions are pinned by commit, and the shipped .sha256 files are finally readable by shasum -c
• Keypad and navigation keys work across platforms — PageUp/PageDown/Home/End on X11 and Windows, Backspace in X11 global hotkeys, and the keypad on X11 with NumLock off or an unreadable layout

Features

• cli: refuse mode command arguments that were accepted and ignored (#1200) (17f304e)
• config: catch a mistyped mode flag in a binding when the config loads (#1201) (9bce87c)
• config: declare per-platform support for every option, flag and action (#1470) (c943b1b)
• config: let hotkey bindings use the Insert key (#1390) (6d144e2)
• hints: make --debug a read-only probe command of its own (#1197) (5db952f)
• linux: animate smooth scroll on every backend (#1473) (eb6d00a)
• linux: capture the screen on KDE through the desktop portal (#1501) (b9b3265)
• linux: capture the screen on X11 and wlroots compositors (#1477) (9ed69c4)
• linux: draw the hint search input badge on every overlay backend (#1476) (b85744d)
• linux: draw the virtual-pointer indicator in grid mode (#1488) (09292c8)
• linux: manage the daemon as a systemd user unit (#1472) (ad4be0b)
• linux: recognise on-screen text for the vision hint strategy (#1480) (54782e3)
• linux: show a paused tray icon and announce a no-CGO build (#1494) (f19319d)
• linux: show notifications and alerts through freedesktop D-Bus (#1471) (134ad2d)
• modes: refuse mode flags that were accepted and then ignored (#1198) (1a3d9c0)
• nix: add services.neru.settings TOML configuration support (#1332) (4bc637e)
• scroll: honor --modifier on scroll actions (#1449) (5f01bb2)
• smooth_cursor: animate relative cursor moves on Linux (#1183) (cb00d07)
• smooth_cursor: animate relative cursor moves with a fixed per-move duration (#1179) (471235a)
• windows: draw the recursive-grid sub-key preview the way Linux and macOS do (#1369) (8120f05)

Bug Fixes

• accessibility: stop priming from opening status-bar menus (#1307) (c8cee2f)
• app: notice the first application switch after the daemon starts (#1355) (4506c3c)
• app: release the overlay after the event tap on shutdown (#1516) (55019b8)
• cli: open docs on Linux (#1467) (83cfeb6)
• cli: point --role examples in help and docs at role spellings that resolve (#1381) (04f214e)
• close the log file even when shutdown cannot flush the logger (#1397) (4bed76b)
• config: keep the grid labelled from the characters it is built with (#1264) (3950c8a)
• config: name the application whose clickable role is rejected (#1387) (1cdea36)
• config: reload the grid without racing a mode activation (#1284) (bab09a2)
• config: report a grid label set that leaves cells unreachable (#1280) (339ae1f)
• config: report an inert held-repeat acceleration setting in config validate (#1260) (530981e)
• config: report every faulty grid label in one validate run (#1285) (dfdb0c8)
• config: update derived values when config set changes their source (#1274) (76e444d)
• config: warn when a clickable role draws nothing on this platform (#1383) (33646b1)
• darwin: build on Apple clang 15 (#1306) (5dcf384)
• darwin: repair overlays the WindowServer silently pins to one Space (#1181) (3129f3a)
• darwin: stop an unmodified scroll inheriting held modifiers (#1450) (1458502)
• darwin: stop macOS actions firing at a point the cursor has left (#1420) (40f3643)
• eventtap: apply per-app hotkey overrides after switching apps mid-mode (#1273) (17a34a9)
• eventtap: make numpad Enter match Return bindings on macOS and stop numpad Clear firing delete (#1377) (aba948d)
• eventtap: make PageUp, PageDown, Home and End work on X11 and Windows (#1382) (cb29a03)
• eventtap: make the Insert key work on X11 and on Windows (#1403) (0e3b536)
• eventtap: make the keypad navigation keys work on X11 with NumLock off (#1395) (e028db3)
• eventtap: make the keypad work on Linux when the keyboard layout cannot be read (#1400) (d92ddc1)
• eventtap: stop the daemon hanging on quit during an app switch (#1514) (9a835e1)
• grid: draw the subgrid with the keys it accepts (#1275) (16564ea)
• grid: drop o from the alphabet a misconfigured grid falls back to (#1282) (ccfc21c)
• grid: stop a repeated character drawing cells nothing can select (#1283) (247c5c1)
• hints: make search_field and switch produce hints on macOS (#1378) (43b664a)
• hints: restore --debug printing elements instead of drawing hints (#1196) (c9bae53)
• hints: stop a hung app blocking the keyboard when a display changes (#1248) (e6ff491)
• hotkeys: keep global hotkeys working while a mode is active (#1520) (b910e19)
• ipc: scope the IPC endpoint to the user running the daemon (#1524) (8075782)
• linux: fall back to the generic font when the configured family is not installed (#1340) (7fcdc3e)
• linux: follow the physical mouse when selecting the active monitor on Hyprland (#1447) (7b0fc43)
• linux: honour the corner radius on hint boundaries and recursive-grid labels (#1357) (c067d44)
• linux: keep the KDE remote desktop grant across daemon restarts (#1485) (f3a0d37)
• linux: let X11 global hotkeys use Backspace (#1401) (3581735)
• linux: let X11 global hotkeys use PageUp, PageDown, Home and End (#1394) (71712a3)
• linux: report a hint placement the overlay cannot draw (#1331) (b1afe4b)
• linux: report focused-window bounds on KWin instead of the active screen (#1489) (600d5d5)
• linux: report the display server neru is actually driving (#1435) (097899b)
• linux: report the notification backend KDE actually has (#1505) (8a7bf05)
• linux: report when a no-cgo build cannot run Wayland global hotkeys (#1432) (f1b6640)
• linux: report where the focused window is now on KDE, not where it was (#1521) (9d98e5f)
• linux: show the subgrid instead of a stale frame when a cell is picked (#1507) (65bec87)
• linux: stop a modifier Neru injects on X11 latching as a sticky modifier (#1504) (a174f1e)
• linux: stop an X11 click carrying modifiers the user is physically holding (#1503) (de52958)
• linux: stop an X11 scroll carrying modifiers the user is physically holding (#1481) (b6c2942)
• linux: stop hint offsets from installing a KWin script on X11 (#1437) (922986b)
• linux: stop reporting a hint search input the overlay never draws (#1354) (10efe0f)
• linux: stop reporting a window with no pid as a failed X11 query (#1513) (c34e3cd)
• linux: stop the grid cells reappearing behind an open subgrid (#1509) (c225a0d)
• linux: stop X11 hotkeys and the KDE geometry helper from sharing what they should not (#1527) (c20a10b)
• linux: tell a failed compositor query apart from an unfocused desktop (#1512) (2f2f435)
• linux: tell an unfocused X11 desktop apart from a failed active-window query (#1499) (6c6f76d)
• logging: keep the daemon log per-user and out of its own content (#1523) (a919ca7)
• make a held scroll key travel as far as the same number of presses (#1498) (1242da8)
• modes: keep a wedged app from stalling a keystroke inside a mode (#1251) (e70dc86)
• modes: keep the keyboard captured across a mode-to-mode switch (#1519) (d07174f)
• modes: stop the monitor-move lock test failing on a busy machine (#1247) (b11d008)
• nix: stop the Linux source build failing on a rejected pipewire cflag (#1517) (0b67937)
• overlay: honour generic font aliases in the monitor picker and virtual pointer (#1336) (4f7d684)
• overlay: honour the virtual pointer's char and font size defaults on macOS (#1358) (297f4e4)
• overlay: keep odd-sized badges at their full size (#1330) (bcc63f7)
• overlay: report a hint label placement the macOS overlay cannot draw (#1360) (d7b5844)
• overlay: report a hint search input anchor the overlay cannot place (#1356) (e1d5558)
• overlay: resolve each font family name from its own spelling (#1308) (c053f52)
• overlay: resolve generic font names the same way on every platform (#1290) (8accea2)
• overlay: stop Linux crashing when the overlay is torn down mid-animation (#1419) (d639a2b)
• scroll: anchor scrolls where the cursor is headed during animated moves (#1182) (c56be6b)
• stop warning about a logger flush that never could succeed (#1388) (303a2e8)
• windows: honour hints.ui.placement instead of pinning every label to the element corner (#1367) (4fd6d76)
• windows: keep the daemon alive across thousands of mode activations (#1526) (9733a3e)

Performance Improvements

• linux: paint the grid subgrid and its pointer in one repaint (#1510) (7696232)
• windows: stop re-resolving the font family on every drawn overlay label (#1361) (c68f80b)