Neru Nightly

This pre-release is automatically built from the latest commit on main.

Warning

This is a nightly build, not a tagged release. It may include incomplete changes, regressions, or experimental behavior. Use a tagged release if you want the most stable experience.

Build Details

• Commit: 36989b7
• Branch: main
• Full SHA: 36989b70440771d5eb8b33e0df577124288163fc

Artifacts

• neru-darwin-arm64.zip for macOS on Apple Silicon
• neru-darwin-amd64.zip for macOS on Intel
• neru-linux-amd64.zip for Linux x86_64
• neru-linux-arm64.zip for Linux ARM64
• neru-windows-amd64.zip for Windows x86_64
• neru-windows-arm64.zip for Windows ARM64

Feedback

If nightly regresses, please include the commit above when filing an issue so we can narrow it down faster.

v1.51.0

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

Warning

This release refuses mode arguments and flags that used to be accepted and ignored, and moves the daemon socket and the macOS log paths.

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

Note

Linux implementations are mainly contributor driven, feel free to help improving it!

• 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 ...

v1.50.0

1.50.0 (2026-08-04)

Overview

Two big themes this release: actions become composable — sequences (neru run), named macros with arguments, failure control, named cursor slots, mouse-button hold/toggle, and neru status --json make Neru properly scriptable — and Linux grows up, with Wayland hints, multi-monitor parity, event-driven per-app config, and dramatically faster hint activation. macOS gets two long-standing memory leaks fixed and correct cursor behavior under Accessibility Zoom. And hints.clickable_roles now speaks one cross-platform vocabulary, so a single config finally works on all three platforms.

Migration Guide

Warning

This release changes the clickable_roles vocabulary (breaking if you customized it) and tightens config validation.

hints.clickable_roles is now platform-neutral (breaking if customized)
Roles are now written as semantic names — button, link, text_field — and resolved to each platform's native vocabulary at config load. Bare native names no longer validate:

hints.clickable_roles: unknown role "AXButton": use "button"

Edit the list once — switch to semantic names, or keep exact native roles with a platform prefix ("ax:AXButton", "atspi:push button", "uia:Custom"). Prefixed entries for other platforms are ignored, not rejected, so the file stays portable. Configs that never customized clickable_roles are unaffected. Run the new neru roles command to see the vocabulary and how each entry resolves on your machine.

Config validation now reaches everywhere execution does
monitor_select bindings, the Mission Control hooks, and steps nested inside a run or --on-exit previously accepted any string. They are now validated at load, so a config carrying a silently-broken step there will be reported as invalid.

mouse_down / mouse_up are deprecated (still work)
Superseded by action left_click --state down / --state up, which works for the right and middle buttons too. Existing configs keep working; the CLI prints a deprecation warning.

---

Actions, Sequences & Macros

• neru run <step> [step...] — run several steps in order as one unit, using the same grammar as hotkey bindings; sequences now behave identically everywhere they're written
• --bail-on-error — mark a step fatal, so ["action left_click --bail-on-error", "idle"] only exits the mode when the click actually landed
• [macros] — named, reusable action sequences with positional arguments, invocable from any binding, --on-exit, neru run, or the new neru macro command. Validated at config load, so a typo fails config validate instead of making a key silently do nothing:

  [macros]
  click_and_exit = ["action left_click --bail-on-error", "idle"]
  
  [hints.hotkeys]
  "Enter" = "macro click_and_exit"

• Named cursor marks — save_cursor_pos / restore_cursor_pos take --slot <name>, so a macro that saves the cursor can't clobber its caller's saved position
• --on-exit on modes — run a sequence after the mode's --action is fulfilled (never on manual escape)
• Hold, release, and toggle any mouse button — --state down / --state up / --toggle on the click actions makes right-drag and middle-drag bindable for the first time; any held button is released on idle, so a drag never sticks
• move_cell — nudge the grid/recursive-grid selection to a neighbouring cell at the current layer instead of backspacing out and re-picking; ships unbound, arrow keys are the natural choice
• Held-key acceleration — optional [held_repeat] ramp scales --dx/--dy up while a key is held

Configuration & CLI

• neru status --json — machine-readable status, replacing grep/awk over display output; the toggles also gain --state on|off|toggle and report their state
• neru roles — list the semantic role vocabulary and how it resolves on this platform; --explain covers your loaded config
• F13–F24 now work in bindings and action feed on Linux and Windows
• neru config reload reports invalid configs immediately instead of timing out behind a modal alert

macOS

• Accurate cursor under Accessibility Zoom — while zoomed, every cursor-driven feature landed hundreds of points off target; events now enter above the zoom transform, and the magnified region pans to keep the cursor visible
• Two memory leaks fixed (the long tail of #1030): CGEventTap Mach ports are invalidated before release, and the accessibility priming walk no longer leaks its entire AX traversal on every focus change. Space changes also skip the expensive WindowServer reattach while the overlay is healthy

Linux

Note

Linux implementations are mainly contributor driven, feel free to help improving it!

• Hints mode on Wayland (wlroots/KDE) via AT-SPI, with per-app config switching on focus change
• Multi-monitor parity with macOS on X11 and wlroots/KWin — enumeration, per-monitor overlays, HiDPI/fractional scaling, hotplug, monitor_select, move_monitor — and overlays now render on the selected monitor instead of always the leftmost one
• Hint activation is dramatically faster — a single AT-SPI Collection query (~5–15×) and compositor-based focus resolution bring activation on busy sessions from 1.5–3s to under 100ms; failures now surface as clear errors instead of silently showing nothing
• Per-app config applies instantly — focused-app changes are event-driven instead of polled
• Smooth cursor animation, mouse action indicator, and hint arrows on X11 and Wayland — at parity with macOS
• Modifier passthrough on Wayland evdev — unbound Ctrl/Alt/Cmd shortcuts reach the focused app while a mode is active
• action feed through uinput when /dev/uinput is writable — works uniformly across X11, wlroots, and KWin
• XDG base directory variables honored for config, data, and logs

Windows

• The full UI Automation control-type range is recognized for hints, so older Win32/WinForms apps can be hinted for the first time
• neru config init no longer writes a config that fails validation (exec_shell pinned a Unix path over the cmd.exe default)

Internals

A large contributor-experience sweep also landed: one package per platform with guardrail tests, compiler-enforced locking in the mode handler, a single shared rendering implementation for both Linux overlay backends, rewritten CLI/config references, and a just ci recipe that mirrors CI exactly.

---

Features

• action: add --bail-on-error to stop a sequence at a failure (#1140) (02c01da)
• action: add --slot for named cursor marks (#1145) (ce5d664)
• action: add move_cell for same-layer grid navigation (#1138) (5abc492)
• action: add run for ordered action sequences (#1139) (224b1ed)
• action: hold, release, and toggle any mouse button (#1119) (f92b475)
• cli: add --json output to neru status (#1143) (887101b)
• cli: add --state to the toggles and a macro command (#1144) (3931d0f)
• config: add [macros] for named, reusable action sequences (#1141) (97597b4)
• config: cross-platform role vocabulary for clickable_roles (#1124) (204cacc)
• held_repeat: accelerate step distance while a key is held (#1120) (ef9e12c)
• linux,wayland: resolve focused application (#1105) (ff0c6fe)
• linux,windows: support function keys F13 through F24 (#1118) (7303270)
• linux: event-driven focused-app changes for per-app config (#1115) (8c9500c)
• linux: feed keys through uinput when /dev/uinput is writable (#1130) (04c885b)
• linux: hint arrows for top/bottom placement (#1111) (6a4112b)
• linux: modifier passthrough on Wayland evdev (#1109) ([31c84f8](https://github.com/y3owk1n/neru/...

v1.49.0

1.49.0 (2026-07-27)

Overview

This release is mostly about making runtime config stick and making the Linux and Windows ports behave like first-class citizens. neru config set is now persistent, the recursive grid can jump straight to a depth, Linux/Wayland input handling got a large stability pass (hotplug, suspend/resume, stuck keys, XKB options), and Windows finally ships a single binary that works as both CLI and daemon — with a proper uninstaller on all three platforms.

Migration Guide

Warning

This release changes Linux default hotkeys and the Windows binary layout. Both need a one-time action.

Linux: default global hotkeys are now empty (breaking)
Neru no longer ships default global hotkeys on Linux, because the old defaults collided with terminal and application shortcuts (Ctrl+Shift+C / copy, Ctrl+Shift+V / paste, …). neru config init no longer writes them either. You now have two options:

• Recommended — bind neru hints, neru grid, etc. in your desktop environment / window manager keybindings
• Or explicitly add a [hotkeys] section back to your own config

Windows: reinstall to get the unified binary (breaking)
Windows previously shipped a GUI-subsystem binary, so no subcommand could print to the terminal it was typed in. It is now built for the console subsystem and releases the console when launched from a shortcut, so a single binary serves as both CLI and daemon. Re-run the installer to pick this up — typing neru now works, while the Start Menu and autostart entries still open no window.

New: persistent config set writes an override file
neru config set now persists across restarts by writing to a *.override.toml file next to your active config (config.toml → config.override.toml). The new load order is:

Defaults → config.toml → config.override.toml → Runtime (in-memory)

Nothing to do if you don't use neru config set — but if you have been using it, be aware that changes now survive restarts. Undo them with neru config reset <key>, or delete the override file.

---

Configuration & CLI

• Persistent neru config set — runtime config changes are now written to a *.override.toml file alongside your config, so they survive daemon restarts. Your hand-written config is never touched
• neru config reset <key> — new command that removes a key from the override file, restoring your configured (or default) value
• --no-reload for both set and reset — defer the reload when you are changing several fields that validate against each other, then commit all of them at once:

  neru config set --no-reload recursive_grid.grid_cols 3
  neru config set --no-reload recursive_grid.grid_rows 3
  neru config set recursive_grid.keys gcrhtnmwv   # commits and reloads

  This makes toggleable grid layouts a single hotkey:

  [hotkeys]
  "Cmd+8" = [
      "config set recursive_grid.grid_cols 3 --no-reload",
      "config set recursive_grid.grid_rows 3 --no-reload",
      "config set recursive_grid.keys gcrhtnmwv",
  ]
  "Cmd+9" = [
      "config reset recursive_grid.grid_cols --no-reload",
      "config reset recursive_grid.grid_rows --no-reload",
      "config reset recursive_grid.keys",
  ]

• Friendlier startup notice — the scary Linux/Windows startup warning is replaced by a short, dynamic capability line, e.g. ⚠️ Neru is running on linux/wayland-wlroots. Run 'neru doctor' for platform capabilities.

Recursive Grid

• --zoom-to-depth flag — drill straight down to a given depth at the current cursor position instead of stepping there key by key. Zero-based (0 is the root), negative values are rejected, and values beyond the maximum depth are clamped instead of erroring:

  neru recursive_grid --zoom-to-depth 2

  To bind it from inside the recursive grid, idle first:

  [recursive_grid.hotkeys]
  "Cmd+1" = [ "idle", "recursive_grid --zoom-to-depth 2" ]

Linux

Note

Linux implementations are mainly contributor driven, feel free to help improving it!

• Recursive grid animations — transition animations are now implemented on Linux for both Wayland and X11, matching the macOS behavior
• Persistent evdev capture with hotplug support — devices under /dev/input/event* were being re-scanned on every mode activation, adding roughly 0.5s of input delay. The capture is now created once and reused, with an inotify watcher on /dev/input/ keeping the device list in sync when keyboards are plugged or unplugged
• No more stuck keys after grab — keys held across a grab could split their state between file descriptors, leaving libinput permanently convinced a key was down. Neru now waits (up to 5s) for held keys to be released before grabbing, suppresses the replayed press events for keys still held, and injects synthetic releases on disable
• XKB options respected — evdev scan codes are resolved through the compositor's libxkbcommon keymap instead of a hardcoded table, so options like caps:swapescape configured in your compositor are honored
• Global hotkeys recover after sleep — hotkeys could become permanently unresponsive after suspend, because /dev/input/event* had not been re-enumerated at the moment PrepareForSleep(false) fired. Capture creation now succeeds with zero devices so the hotplug watcher can pick them up as udev populates them, wake-up retries are bounded (5 attempts, 500ms backoff), and the health check no longer reports a failed listener as healthy
• No more hangs or repeated permission prompts on resume — hotkey teardown now times out and recovers instead of hanging the daemon after deep sleep, and the RemoteDesktop session is no longer reset on every sleep cycle, so you are not re-prompted for Remote Control permission (input actions retry once if they hit a stale connection)
• 100% CPU busy-loop fixed — the evdev hotplug inotify watcher was created with IN_NONBLOCK, so reads returned EAGAIN immediately and spun the loop
• Cursor synced before mode activation — the Wayland cursor-position cache is refreshed before a mode activates, so overlays and indicators anchor to the real pointer position instead of a stale one (often screen center) after you move the mouse manually
• AT-SPI init is now gated — accessibility activation is conditional on your hints configuration, and the state is always reset on startup and shutdown

Windows

• One binary for CLI and daemon — built for the console subsystem, releasing the console when started from a shortcut rather than a terminal. neru <subcommand> now prints to the terminal you typed it in, while the Start Menu and autostart entries still open no window. The embedded icon is preserved
• Proper Windows paths everywhere — PATH entries, shortcuts and registry values are now real Windows paths instead of mixed or POSIX-style ones
• PATH written through the registry — replaces setx, which truncates at 1024 characters and flattens other tools' expandable entries
• Optional Start Menu shortcut — what actually makes the app searchable from the taskbar; PATH alone does not
• ~/.config/neru is now discovered — in addition to %APPDATA% and XDG_CONFIG_HOME, so a config carried over from a Unix dotfiles repo works unchanged. %APPDATA% remains the write location

Install & Uninstall

• just uninstall on all three platforms — undoes each install step in reverse. Config and logs are kept unless --purge is passed, so -y alone can never delete a hand-tuned config; --purge lists the fully resolved directories before deleting anything. It deliberately leaves alone what it did not install — a binary on PATH that is not our symlink, and the Linux input group, which other tools may depend on

Docs & Internals

• Cross-platform feature parity tables — docs/CROSS_PLATFORM.md now spells out per-feature support across macOS, Linux (X11 / Wayland variants) and Windows in much more detail
• macOS integration tests — the main run loop is now serviced during integration tests, fixing flakiness in run-loop-dependent tests

---

Features

• config: add --no-reload for set and add reset (#1083) (2920864)
• config: persistent config set via override files (#1082) (6398fa5)
• install: unify the Windows binary, add cross-platform uninstall (#1103) (fc8e1f0)
• linux: support animation for recursive grid (#1089) (b800247)
• recursive_grid: add --zoom-to-depth flag (#1077) (3dfe895)

Bug Fixes

• linux,wayland: make evdev capture persistent with kb hotplug support (#1086) (e345661)
• linux,wayland: prevent hotpulgLoop busy wait (#1088) (c519875)
• linux,wayland: prevent stale evdev state from causing stuck keys after grab (#1087) (cdd466a)
• **linux...

v1.48.0

1.48.0 (2026-07-20)

Overview

This release is packed with configurable goodness — the action system is more powerful, the recursive grid is more customizable, and the virtual pointer is now fully configurable. There are some important migration notes to be aware of.

Migration Guide

Warning

This release contains breaking changes to virtual pointer config and a cleanup opportunity for hints config.

Virtual Pointer config has changed (breaking)
The virtual pointer is now drawn using a character instead of a circle with a defined radius. If you have custom virtual pointer config, you need to update it:

• Old: radius option no longer works
• New: Configure char, font_size, and font_family under [virtual_pointer.ui]
• See Virtual Pointer below for details

Bundle auto-detection for Hints (cleanup)
Neru now auto-detects bundle types (Chromium, Electron, Firefox, WebKit, etc.) automatically. This means you can:

• Remove all hints.additional_ax_support entries from your config
• Stop manually adding bundle names to your configuration
• The accessibility tree is now woken directly — no more AXManualAccessibility/AXEnhancedUserInterface attribute manipulation

New Recursive Grid UI config options
Four new config options were added for the recursive grid:

• recursive_grid.ui.label_char — sets the character used for grid labels
• recursive_grid.ui.sub_key_preview — enables sub-key preview (boolean)
• recursive_grid.ui.sub_key_preview_label_char — sets the character for sub-key preview labels
• recursive_grid.ui.label_autohide_multiplier — prevents labels from being cramped at high zoom levels (default: 1.5)

---

macOS

• New cursor actions — neru action hide_cursor and neru action show_cursor let you hide the system cursor and use a customizable virtual pointer instead. Great for presentations or distraction-free workflows
• Auto-detect bundle types — hints now automatically detect app bundle types. This replaces the old hints.additional_ax_support approach and provides a zero-config experience
• Vision hints --split-word — new --split-word flag for vision-only strategy that segments visible text into individual clickable labels. Useful for text selection workflows
• Cursor auto-rehide — lightweight polling added to re-hide the system cursor when macOS auto-unhides it (right-click, Mission Control, etc.)
• Lightweight space change handler — macOS notification handlers were separated to prevent window server overload during frequent active space changes (ActiveSpaceDidChange now uses a lightweight path)

Linux

Note

Linux implementations are mainly contributor driven, feel free to help improving it!

• Native relative pointer motion — move_mouse_relative now emits zwlr_virtual_pointer_v1.motion directly on wlroots compositors, keeping movement anchored to the actual pointer position instead of a cached center position
• Cursor cache sync — cursor cache is now synced after relative moves so indicator polling reflects the current position
• Subkey preview autohide — corrects the autohide calculation to check subcell dimensions properly
• Virtual pointer rendering — configured virtual pointer cursor now renders correctly on Linux and Windows by passing the configured styles and fonts
• nocgo stubs added — improves build consistency for non-CGo environments

Action System

• --modifier support — you can now pass modifier keys (e.g., ctrl, alt) with --action. Supports multiple modifiers separated by commas:

  neru hints --action left_click --modifier alt,ctrl

• Multi-click support — --action and action now support comma-separated lists of actions for multi-click:

  neru hints --action left_click,left_click       # double click
  neru action left_click,left_click,left_click    # triple click

• --hide-on-empty-search — new flag for hints mode that hides labels when the search query is empty (used with --search)
• cycle_hint separation — fixed an issue where tab/cycle inputs in --action + --search mode would unintentionally trigger actions or close the interface. Cycling now correctly moves the cursor without firing the action

Virtual Pointer

• Fully customizable — the virtual pointer is now drawn as a configurable character instead of a circle with radius. New [virtual_pointer.ui] section:

  [virtual_pointer.ui]
  char = "●"      # character to use for the pointer
  font_size = 16  # size of the pointer character
  font_family = "Helvetica"  # font family

Recursive Grid

• New config options — label_char, sub_key_preview, sub_key_preview_label_char, and label_autohide_multiplier for granular control over grid labels
• Even cell distribution — cells are now evenly distributed with centers rounded to the nearest pixel, preventing visual misalignment
• Contiguous remainder pixels — remainder pixels are now distributed contiguously so the grid fills its bounds with at most 1px difference between cells. The calculation logic was also refactored to be shared across all renderers
• Font family passthrough — sub-key previews on macOS now respect the configured font family for consistent styling

CLI

• neru config set <key> <value> — new command to change configuration at runtime using dotted TOML path notation. Supports strings, integers, booleans, floats, colors, and string arrays:

  neru config set hints.hint_characters "bmwvz;qjkxdhtns"
  neru config set recursive_grid.ui.highlight_color "#B00A1338"

• neru config validate — CLI output now writes to stdout, keeping errors on stderr, making output pipeable

Other Highlights

• app_configs merge fix — fixed an issue where app_configs failed to merge correctly when the root config was set differently
• Integer overflow guard — allocation size computations now guard against integer overflow

---

Features

• allow --modifier in mode --action (#1040) (ba7cb19)
• allow multiple clicks for --action and action (#1039) (afea90a)
• cli: add neru config set for runtime config changes (#1071) (a130074)
• darwin,action: add hide and show system cursor action with virtual pointer (#1059) (b3d6feb)
• darwin,hints: auto-detect bundle types (#1035) (db5682f)
• hints,cli: add --hide-on-empty-search flag when search is empty (#1044) (a850c32)
• hints,vision,darwin: add --split-word flag for vision only (#1041) (dfc76db)
• make virtual pointer fully customisable (#1061) (7c18422)
• recursive_grid,config: add label_autohide_multiplier to hide cramped labels (#1054) (d8c4eb3)
• recursive_grid: add label_char and sub_key_preview_label_char config options (#1045) (d95bb36)

Bug Fixes

• cli: write output to stdout so that they are pipeable (#1047) (bcddd01)
• config: ensure app_configs merges properly without defaults (#1042) (204c0fd)
• darwin: auto-rehide cursor when macOS reveal it (#1065) (a2f6184)
• darwin: use a lightweight handler for space changes (#1032) (83351be)
• guard against integer overflow in allocation size computations (#1074) (f7136b9)
• hints: separate cycle_hint from action execution (#1043) (b65861f)
• linux,wayland: sync cursor cache after move relative (#1056) (b0f6a97)
• linux,windows: ensure proper render for configured virtual pointer (#1063) ([2f859e1](http...

v1.47.0

1.47.0 (2026-07-13)

Overview

This release are mostly improvement of existing features and bugs around macOS and linux, but they are useful! The rest are docs update.

Linux

Note

Linux implementations are mainly contributor driven, feel free to help improving it!

• support for action feed command to feed keys back to the OS
• fixes KDE EIS keyboard drop bug
• recover from stale evdev and libei sessions
• properly render recursive grid's sub key previews

macOS

• support root app_configs for global hotkey overrides per app
• allow app_configs hotkey to override the global hotkeys
• fixes sticky modifier that incorrectly registers modifiers on mode switches
• keep hints labels on screen if we have any and update the new labels without flicker
• lowered minimum size heuristic for hints on chromium and electron from 15 to 10

All Platforms

• support --mode flag for action feed to feed keys back to neru instead of to the OS.
• now every font sizes in configuration support values between 1 to maxInt32.

---

Features

• add app_configs for global hotkey overrides (#1008) (b1a4c67)
• cli,action: add --mode flag to action feed to feed keys into neru (#999) (fe23531)
• hotkeys: let per-mode hotkeys override a global hotkey on the same key (#993) (c95ccf5)
• linux,wayland,kde: add action feed support (#1013) (c28300b)

Bug Fixes

• darwin,stick_modifier: prevent random sticky modifier toggles (#1011) (22bc23c)
• hints: keep labels on screen during refresh instead of blanking (#1012) (4638626)
• hints: lower down minElementSize to 10 for smaller sized hints (#1020) (eefb876)
• linux,kde: work around KDE EIS keyboard drop bug (#1021) (8ff4a32)
• linux,recursive_grid: render subkey preview properly when enabled (#995) (1da2cd2)
• linux: recover from stale evdev/libei connections after sleep and config reload (#1023) (a43eb4e)
• lower down minimum font size to 1 and add missing validations (#1024) (c196b93)

Documentation

• add bernatGene config showcase (#1010) (32958a6)
• tips: add commands to open a new window and edit config tips (#997) (d2816d3)
• tips: add mode-cycling and element-targeted shortcut recipes (#1004) (fcbcd5b)

v1.46.1

1.46.1 (2026-07-07)

Overview

This is a patch release mainly for macOS builds to ensure releases works properly. Nothing else changed.

Bug Fixes

• darwin,ci: pin arm64 CI runner & enforfe macos 14 minimum (#990) (e80285b)

v1.46.0

1.46.0 (2026-07-06)

Overview

The biggest highlight for this release is Linux KDE support, plus other small features and bug fixes.

Windows

Note

Windows implementations are mainly contributor driven, feel free to help improving it!

• Overlay now shows on the right active monitor

Linux

Note

Linux implementations are mainly contributor driven, feel free to help improving it!

• Added KDE linux support, nice!

macOS

• Added a new monitor_select mode for better multi-monitor workflow
• Move global hotkeys to newer CGEventTaps
• Ensure mode and sticky modifier indicator always visible (No longer gone after wake from sleep)

All Platforms

• wait_for_mode_exit now has a --bail flag to abort when manual escape

---

Features

• cli: add --bail flag to wait_for_mode_exit for chain abort-on-cancel (#970) (92289a2)
• darwin: new monitor_select mode with overlay (#963) (6ba2aab)
• darwin: replace Carbon hotkeys with per-hotkey CGEventTaps (#967) (fd77dd5)
• linux,kde: add support for KDE linux (#931) (b7563a4)

Bug Fixes

• darwin,monitor_select: allow current monitor to be selectable (#964) (ad2dcb5)
• darwin,monitor_select: remove unneeded isCurrent theming (#965) (242e37b)
• darwin: keep indicators visible after wake changes (#962) (444ccf9)
• darwin: keep mode indicator visible across Spaces (#956) (34b9499)
• windows: correct active monitor detection (#966) (b7b03e1)

v1.45.0

1.45.0 (2026-06-29)

Overview

This is a big release — the headline is initial Windows support (and yes, we are now considered a true cross platform software), bringing neru to a whole new platform alongside refinements across all ports.

Windows

Note

Windows implementations are mainly contributor driven, feel free to help improving it!

• Initial native Windows support with a full implementation
• Overlay rendering rewritten with real per-pixel alpha and full theme support
• Native alert dialogs for validation and startup errors
• App icon now embedded in the .exe
• Daemon auto-launches when running the .exe
• Non-modifier key-down events are consumed to prevent passthrough to other apps
• Proper Windows paths for config, shell, and path validation
• Font resolution now works correctly on Windows
• Hint badges render atomically for correct z-ordering
• Hint roles and styling are properly aligned

Linux

Note

Linux implementations are mainly contributor driven, feel free to help improving it!

• Wayland overlay now renders at the correct output buffer scale for proper HiDPI display
• Fixed keyboard grab leak from evdev EINTR and blocked poll situations

macOS

• Mode indicator now stays visible after app reactivation

All Platforms

• label_direction option added for hints, offering a different layout algorithm to control label placement direction
• No more overlay redraw flash when exiting a mode (grid)

---

Features

• hints: add label_direction with different algo (#934) (9cf45b7)
• linux,wayland: render overlay at output buffer scale (#955) (8c8482a)
• windows,overlay: rewrite overlay renderenig with real per-pixel alpha and full theme support (#950) (8b1fa57)
• windows: add native alert dialogs for validation and startup (#948) (1b52c02)
• windows: embed app icon in .exe (#949) (90850f0)
• windows: initial basic support implementation (2b637ba)

Bug Fixes

• darwin,overlay: keep mode indicator visible after reactivation (#936) (c41f96f)
• grid: avoid overlay redraw flash on mode exit (#954) (5f07607)
• linux,wayland: prevent keyboard grab leak from evdev EINTR and blocked poll (#953) (d1bea3d)
• windows,config: use proper windows path for config, shell and path validation (#943) (c679e6f)
• windows,hints: render badges atomically for correct z index (#952) (208db03)
• windows: align roles for hints and fix styling (#951) (7677bb4)
• windows: auto launch daemon when running .exe (#944) (6d504ef)
• windows: consume non-modifier key-down events to prevent passthrough to apps (#947) (a10a27a)
• windows: ensure exe launches and quit properly (#946) (f12d0cd)

v1.44.1

1.44.1 (2026-06-13)

Overview

This release is more targeted on linux users:

• Long content scrolling on linux is now fixed
• Sticky badges will now follow the cursor properly (when you move the mouse via neru action, still don't have a good solution to sync with the mouse movement yet)
• Sticky modifier is now much more reliable (need evdev setup)
• Properly resolve fonts on all ports, which means linux will respect on the configured font now, prettier!

Bug Fixes

• linux,wayland: send 1-notch scroll events to prevent clipping (#927) (0a12df9)
• linux: badge overlay to follow cursor pointer (#920) (5288eee)
• linux: improve sticky modifier detection (#926) (8c685dd)
• resolve fonts via ports on all platforms (#928) (e807897)