y3owk1n/neru v1.48.0

on GitHub

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

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

• 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)
• linux: add nocgo stubs for consistency (#1037) (2c27777)
• linux: ensure subkey preview autohide checks the subcell dimensions (#1066) (c1a436d)
• linux: use native relative pointer motion (#1055) (542866f)
• recursive_grid,darwin: pass font family to sub-key preview renderer (#1048) (75ac644)
• recursive_grid,overlay: evenly distribute cells and round centers to nearest pixel (#1046) (e0fee73)
• recursive_grid: distribute remainder pixels contiguiously (#1062) (b9d2367)

Documentation

• cli: rewrite with proper grouping (#1068) (860db8b)
• troubleshooting: Add notes about element size and element type, clean up Electron/Browser troubleshooting (#1029) (e6d0211)
• troubleshooting: explain missing hints on multi-monitor setups (#1031) (14ec9ed)