y3owk1n/neru v1.59.0

on GitHub

1.59.0 (2026-10-18)

This release is mostly about hint search. You can pick one of several matches by typing its label after the search text, act on it without Return using --confirm-on-label, and type with an input method, dead keys or shifted symbols on Wayland, X11 and Windows. A new segment strategy finds targets from the screen's pixels alone, on every platform. Linux and Windows honour more hint options, and macOS gets crash and stability fixes.

Migration Guide

A mode that refuses to open now fails instead of reporting success.
When the focused app is in excluded_apps, secure input is on, or Neru is stopped, neru hints, neru grid and the other mode commands used to print "mode activated" and exit 0. They now exit 1 with the reason and a code, such as focused app is excluded (code: ERR_INVALID_INPUT). neru monitor_select fails the same way when it cannot show the picker.

Hint search

• Type a label after the search text to pick one of several matches. save a keeps the save matches whose label starts with A, and Return acts on the one left. A label never hides a text match, so a word in the query is never mistaken for one
• --confirm-on-label acts as soon as a typed label leaves one match, with no Return. A single match by text alone still waits for Return. action search_hints takes the same flag
• Input methods, dead keys and shifted symbols work in hint search on Wayland, X11 and Windows, as they do on macOS. Wayland needs a compositor with layer-shell, such as Sway, Hyprland, niri, KDE or COSMIC. On GNOME, or wherever the field cannot open, search reads raw keys as before
• Each keystroke in search is about ten times faster
• Return acts on the match it confirmed. A key pressed quickly after Return could act on a hint from the next set instead

[hotkeys]
"Primary+Shift+Space" = "hints --action left_click --search --confirm-on-label"

segment strategy

• segment finds targets from the window's pixels alone, with no accessibility tree and no OCR. It puts a hint on each button, field and icon, and on each word, so a link inside a sentence gets its own hint. It needs Screen Recording on macOS, like vision and contour
• hints.segment.targets picks what gets a hint. words is the default, phrases hints each run of same-color words once, and controls skips text entirely

[hints]
strategy = "segment"

[hints.segment]
targets = "phrases"

Modes

• --toggle works with a --strategy or --capture-scope list. Each press moves to the next entry, and the press on the last entry closes the mode, so hints --strategy axtree,contour --toggle goes axtree, contour, close
• Hints stay open after move_monitor with a screen-reading strategy, and label the display you moved to
• A left click ends a held drag where it lands. The button used to stay recorded as held, so the next toggle did nothing and leaving the mode sent a stray mouse-up

Linux and Windows hints

• hints.max_depth and ignore_clickable_check now work on Linux and Windows, and visible_check_enabled on Linux, instead of warning at load that they do nothing
• The vision strategy finds icon buttons, not just text, and the hints.vision rectangle options apply
• Hints read an element's description and value, so --text matches what it matches on macOS. Disabled elements, such as a greyed-out button, get no hint

Scripting and CLI

• neru query hints reports source, identifier and focused for each element. A script can find an element by the ID its developer gave it, even when its text changes or is translated
• neru config set accepts a value that depends on your other settings, such as hints.detect_mission_control true when include_dock_hints is already on
• neru doctor shows why the daemon refused, such as a version mismatch after an upgrade
• A reload that changes excluded_apps applies to every mode activation, not only to hotkeys
• The macOS and Linux install script stops the running daemon on update and uninstall, instead of leaving the old version running

macOS

• An app that returns a short accessibility answer no longer crashes Neru
• Background tree priming stays small. When an app comes to the front, Neru reads its accessibility tree ahead of the first hints. That read now skips elements it has seen, stops at 2000 elements, and is cancelled when you switch apps, so only one runs at a time
• Screen-reading strategies capture faster, and a stalled capture can no longer freeze key handling for up to five seconds
• Screen-reading strategies no longer pick up Neru's own labels as targets during a refresh
• Hint search no longer counts as a switch to Neru, so on_app_focus stops firing with Neru's own bundle ID

Linux

• More GTK apps get hints, including GTK 3 text fields, GTK 4 apps, and GNOME apps whose name differs from their app id
• Scrolling left and right goes the right way, rotated wlroots displays capture correctly, and keys held on a keyboard that disappears are released

Windows

• Commands no longer hang on the IPC pipe. Some command lengths never reached the daemon and timed out
• Accessibility, OCR and service results are no longer read back empty at random
• Large scrolls go the full distance instead of wrapping

Features

• cli: toggle a cycle list with --toggle (#1842) (11b6e48)
• hints: add --confirm-on-label for search (#1838) (9a0fbc7)
• hints: add segment strategy (#1809) (97c81c4)
• hints: detect button shapes in the vision strategy on Linux and Windows (#1800) (2dd7779)
• hints: honour hints.max_depth on Linux and Windows (#1788) (9644301)
• hints: honour ignore_clickable_check on Linux and Windows (#1798) (58b43ad)
• hints: honour visible_check_enabled on Linux (#1799) (cfcb4e0)
• hints: narrow a search by the label on last space separator (#1837) (427ea06)
• hints: report source, identifier and focus, and skip disabled elements (#1787) (b23012e)
• hints: type into hint search through a real text field on Wayland (#1802) (4533bdb)
• hints: type into hint search through a real text field on Windows (#1803) (1927af4)
• hints: type into hint search through a real text field on X11 (#1804) (2ef0970)

Bug Fixes

• action: end a held drag where a left click lands (#1814) (d1fd4a2)
• cli: allow config set to pass for depended settings (#1820) (253be44)
• cli: report properly when a mode failed to activate (#1826) (69222f5)
• cli: show why the daemon refused in neru doctor (#1824) (0ed2101)
• config: apply excluded_apps changes on reload everywhere (#1819) (0309787)
• darwin: build on the macOS 15 SDK again (#1810) (f1aa79e)
• darwin: ignore priming neru self on hint search (#1825) (98e6ff7)
• darwin: keep our own labels out of vision based scans (#1821) (a8ccb56)
• darwin: make tree priming cancellable with cap (#1841) (2e36858)
• darwin: make tree priming cancellable with cap (#1841) (62412cc)
• darwin: prevent crash on fewer element attributes returned (#1815) (fbef0c7)
• darwin: stay quit after Quit instead of being restarted by the login service (#1813) (e3e7f07)
• hints: apply detect_mission_control on reload (#1827) (d489b29)
• hints: keep capital letters typed into hint search on Linux and Windows (#1801) (e2bb9a8)
• hints: make Return in hint search select the match it confirmed (#1831) (05f189d)
• hints: read element description and value on Linux and Windows (#1786) (79e40a0)
• hints: refresh old labels for visions on reactivate on Linux and Windows (#1830) (43b7f65)
• hints: show hints after move_monitor (#1822) (a1fb110)
• install: stop the running daemon on update and uninstall instead of pausing it (#1812) (5ca5a6d)
• linux: capture rotated wlroots displays correctly (#1823) (7eb9c69)
• linux: hint GNOME apps whose name differs from their app id (#1790) (e0d08c1)
• linux: hint GTK 3 text fields (#1784) (66de454)
• linux: hint GTK 4 apps again and place them where the window position is known (#1789) (4da72d3)
• linux: name the GNOME Shell extension while it is still connecting (#1832) (f730d1e)
• linux: release keys a keyboard held when it disappears (#1835) (8eace01)
• linux: report clicks and drags with no display backend (#1828) (2bb1024)
• linux: scroll left and right correctly (#1811) (4a38a04)
• windows: keep COM out-parameters valid across a stack move (#1818) (c5aac45)
• windows: scroll the full distance on large scrolls instead of wrapping (#1817) (9bfdb94)
• windows: stop commands hanging on the IPC pipe (#1816) (fee5c61)

Performance Improvements

• hints: capture only the hinted region and cache the display list (#1808) (5d1a5d8)
• hints: normalize search text once per hint scan (#1829) (195f003)