Skip to content
Nightly docs track main and may describe features that are not released yet. Docs for the current release (v1.63.0) are here.

Platform support

What works on macOS, Linux and Windows, and what does not. How each platform implements it is in the contributor docs.

PlatformStatusDefault PrimaryShips as
macOS 14+StableCmdNeru.app, codesigned
LinuxBetaCtrlBinary and install script
Windows 10+BetaCtrlBinary and install script

On Linux, Neru supports X11 and the Wayland desktops listed in Linux setup.

  • Stable: fully featured and proven in daily use. A gap here is a bug.
  • Beta: ready for daily use, and every mode works as on a stable platform. Something is still missing, or what is there is proven only by CI.
  • Alpha: core navigation works, but hint coverage is incomplete and per-app config does not re-apply on focus change.

Windows has one known gap and Linux has two, under Known gaps. Both stay Beta because CI proves them rather than daily use. A Beta platform becomes Stable after six releases in a row with no bug filed against it alone.

Legend: ✅ works · ⚠️ works with a limit, see the note · ❌ not available · ➖ macOS only, see Platform exclusives

CapabilitymacOSLinux X11Wayland (wlroots)Wayland (KDE)Windows
Grid, recursive grid, bisect✅✅✅✅✅
Hints from the accessibility tree✅⚠️ ¹⚠️ ¹⚠️ ¹⚠️ ¹
Hints from OCR (vision)✅⚠️ ²⚠️ ²⚠️ ²⚠️ ²
Hints from shapes (contour)✅✅✅✅✅
Hints from layout (segment)✅✅✅✅✅
Hint search⚠️ ³⚠️ ³⚠️ ³⚠️ ³⚠️ ³
Menu bar, Dock and other system surfaces in hints✅➖➖➖➖
Scroll mode✅✅✅✅✅
Monitor select✅✅✅✅✅
Vim mode✅⚠️ ¹⁶⚠️ ¹⁶⚠️ ¹⁶⚠️ ¹⁷
Clicks, drag, modified clicks✅✅✅ ⁴✅ ⁴✅
Smooth cursor and held-key glide✅✅✅✅✅
Smooth scroll✅⚠️ ⁵✅ ⁵⚠️ ⁵✅
Global hotkeys✅✅⚠️ ⁶⚠️ ⁶✅
Modifier passthrough✅❌⚠️ ⁶⚠️ ⁶✅
Sticky modifiers, action feed✅✅✅✅✅
Copy a hint’s text (copy_text)✅ ¹⁵⚠️ ¹⁴ ¹⁵⚠️ ¹⁴ ¹⁵⚠️ ¹⁴ ¹⁵✅ ¹⁵
Per-app config✅✅⚠️ ⁷⚠️ ⁷✅
Screen capture for hints✅⚠️ ¹²⚠️ ¹²⚠️ ⁸ ¹²✅
Tray icon✅✅✅✅✅
Notifications✅⚠️ ⁹⚠️ ⁹⚠️ ⁹⚠️ ¹¹
Alerts✅⚠️ ⁹⚠️ ⁹⚠️ ⁹✅
Login service (neru services)✅⚠️ ¹⁰⚠️ ¹⁰⚠️ ¹⁰✅
Hide the system cursor✅➖➖➖➖
Hide overlays from screen share✅❌❌❌⚠️ ¹³

COSMIC matches the KDE column. GNOME matches it too, except that per-app config and window positions need the Neru GNOME Shell extension, see GNOME.

¹ Hint coverage depends on the app. Linux reads AT-SPI, and each app decides what it exposes. Chromium and Electron apps need --force-renderer-accessibility. Windows misses elements an app exposes only in UI Automation’s raw view. Where hints are thin, use vision, contour, segment or a grid mode. On some Wayland compositors hints in native apps can be offset, see wlroots compositors. The identifier that neru query hints reports is empty on Linux for GTK 3 apps, which set no AT-SPI AccessibleId. GTK 4 apps report no screen positions, so Neru places their hints only where it can read the window’s position. On X11, and on Wayland wherever Neru gets no window position, their hints stack at the top-left corner. hints.visible_check_enabled keeps every element in GTK 4 apps, which answer no hit-test. Elsewhere on Linux it drops only elements something else in the same window covers. The app answers the hit-test itself, so it never sees other windows, on X11 or Wayland.

² Text and shapes come from two engines. Linux (tesseract) and Windows (Windows.Media.Ocr) read the words, and the contour detector finds button shapes in the same frame. It uses its shipped thresholds, not [hints.contour], and scores every shape one, so the *_confidence options never drop a shape. Windows also needs an OCR language pack, and ignores the *_confidence options for words too. Neru never logs or stores recognized text.

³ Hint search reads the keys Neru captures, the same way on every platform, so an input method never sees them. You find text in another script by typing its romanization, so shenzhen finds 深圳 and boris finds Борис. Japanese kanji match by their Chinese reading. A shifted key types what a US layout puts on that key. A layout with other characters there, such as the digits on AZERTY, cannot type them.

⁴ Modified clicks on Wayland need a writable /dev/uinput, see Linux setup.

⁵ Smooth scroll granularity. X11 scrolls in whole wheel notches, so a scroll_step under 45 px is one unanimated click. X11 and KDE scrolling is untested on hardware. On Hyprland a scroll with a modifier held moves in whole notches.

⁶ Wayland hotkeys and passthrough need the input group, see Linux setup. Without it, bind modes in your compositor.

⁷ Wayland identifies apps by app_id, which is what bundle_id matches, see App identity.

⁸ KDE asks once before the first screen capture, see Screen-sharing consent.

⁹ Linux alerts and notifications need a notification daemon, such as mako or dunst, running or D-Bus activatable. Alerts arrive as notifications, not dialogs. Without a daemon, both report that they are not supported, and the two startup alerts go to stderr.

¹⁰ The login service needs systemd. On runit, OpenRC or s6, run neru launch from your session.

¹¹ Windows notifications are balloons on the tray icon, so with systray.enabled = false they report that they are not supported. Alerts are dialogs and need no tray.

¹² Linux takes Neru’s overlay off the screen for each capture, because no Linux display server can leave one window out of it. While a mode is open, a hints refresh or neru action snap with vision, contour or segment clears the overlay, waits for the compositor to draw a frame without it, captures, and puts it back. The overlay is gone for that long, at least one frame, and the click indicator stays in the capture. Windows before Windows 10 version 2004 captures the overlay. There snap refuses those strategies with ERR_NOT_SUPPORTED while a mode is open, and a hints refresh takes the labels off before it captures. macOS and newer Windows leave the overlay out of the capture.

¹³ Windows hides the overlay from every capture, screenshots and recordings as well as screen shares, while it stays on the monitor. It takes Windows 10 version 2004 or later, and an earlier build leaves the overlay in the share.

¹⁴ Linux copies through a command-line tool, since setting the clipboard needs a process that keeps serving it. Linux setup names the tools to install. Without one, neru action copy_text fails with ERR_NOT_SUPPORTED, and a copy from hints mode copies nothing and logs a warning. Neru looks for the tool on every copy, so one installed while it runs works right away.

¹⁵ How copy_text reads a hint found on screen differs by platform. On macOS, hints mode places those hints from one read of the whole screen, and that read gets small text wrong. While hints mode is open, copy_text reads the hint’s own box again, enlarged, and copies that. It also gives contour and segment hints, which carry no text of their own, something to copy. Once hints mode has closed, as for an --on-exit copy after a click, it copies what the hints pass read. Linux and Windows always copy what the hints pass read, since their OCR reads small UI text word for word from the whole screen. contour and segment hints there have nothing to copy.

¹⁶ Linux vim mode reads Latin script, plus the languages in other scripts the daemon’s locale names in LANGUAGE, LC_ALL, LC_MESSAGES or LANG, such as Chinese or Russian, when their tesseract data is installed beside eng.traineddata. The accurate read reads them, so until that finishes a line in one shows as noise. Vim mode reads a line that mixes English with a word of Russian or Arabic as English. tesseract reads Korean less reliably than Chinese and Japanese, so a Korean line can come back in pieces. It reads 「 and 」 as Latin letters, and its tessdata_fast models misread more than the standard ones distributions ship. On niri, as on the other wlroots compositors under wlroots compositors, a tiled window gives no bounds on niri 26.04 and earlier, and vim mode reads the whole screen. Floating the window reads just the window. Later niri releases report tiled windows too. On Wayland, edits and typing need the keyboard proxy, which needs a readable /dev/input and a writable /dev/uinput. Without it Neru holds the keyboard through its own overlay while a mode is open, where a key it typed would come back to it. So there, while a mode is open, vim mode refuses each edit and says why in its status line, and action feed is refused too.

¹⁷ Windows vim mode reads two languages at most. The fast read uses the first language in the account’s list that has an OCR pack, since Windows.Media.Ocr builds its engine from that list. The accurate read also reads with the first Chinese, Japanese or Korean language in the list when its OCR pack is installed. That language can stay below English, so apps keep their English menus. Until the accurate read finishes, a line in that language shows as noise or is missing. The Chinese engine reads small text less reliably at 100% scaling than at 200%. Other packs further down, such as Russian below English, go unused. The engine gives a box for each word only, so vim mode places each character by its own ink. In a word whose letters touch, the cursor can sit a little off a character.

Windows on ARM draws overlays with GDI, the CPU fallback, instead of Direct2D.

Window rules. Every overlay window is named neru-overlay: the panel title on macOS, WM_CLASS and window name on X11, the layer-shell namespace on Wayland, and the window class on Windows. Match it to keep overlays out of a tiling layout or a screenshot tool.

Options, mode flags and actions that do nothing on some platform. Writing one there is not an error, so one config works everywhere. Neru warns once at load, and neru doctor lists them under platform_support.

WordsmacOSLinuxWindowsWhy
general.hide_overlay_in_screen_share, hooks.on_screen_share_hide✅❌✅hiding the overlay from a screen share is an NSWindow sharing level on macOS and a display affinity on Windows, with no X11 or Wayland counterpart
hints.include_menubar_hints, hints.additional_menubar_hints_targets, hints.include_dock_hints, hints.include_nc_hints, hints.include_stage_manager_hints, hints.include_pip_hints, hints.include_screen_capture_hints✅❌❌the menu bar, the Dock, Notification Center, Stage Manager, picture-in-picture and the screen-capture chrome are macOS surfaces with no counterpart
hints.detect_mission_control, hints.on_mission_control_activated, hints.on_mission_control_deactivated, hooks.on_mission_control_activated, hooks.on_mission_control_deactivated✅❌❌Mission Control is a macOS concept, so the detection never fires and the hooks never run
grid.prewarm_enabled✅❌❌only the darwin grid overlay prewarms its layers; the other backends draw on demand
hints.vision.minimum_confidence, hints.vision.button_min_confidence, hints.vision.generic_clickable_min_confidence✅✅❌Windows.Media.Ocr reports no per-word confidence, so every word scores one there and a floor keeps everything; the Vision framework and tesseract score each word
hide_cursor (action), show_cursor (action)✅❌❌a Wayland client may not hide another client’s cursor, and the blessed Linux stack is Wayland; Windows has no equivalent either

Features on exactly one platform, because the others have no way to do them. Anything else missing is a gap.

FeaturePlatformWhy it is exclusive
System cursor hide + virtual-pointer replacementmacOSA Wayland client may not hide another client’s cursor. X11 could, but the supported Linux stack is Wayland, so shipping it on one backend would not be parity
Secure input detectionmacOSRead through a private macOS API. Neither X11 nor Wayland has the concept

Linux and Windows have no exclusives.

A gap is anything you can write that means less on a platform than on macOS. A boundary is a requirement the platform imposes, not something Neru lacks.

Linux: two gaps.

  • Vim mode reads Latin script and the languages the locale names, with their tesseract language data installed. macOS reads every script it knows.
  • A Wayland monitor’s resolution or scale change needs a daemon restart before overlays fit it again. Plugging in or removing a monitor is tracked live.

These are boundaries, not gaps:

  • Wayland global hotkeys need the input group (Linux setup).
  • On wlroots compositors other than Sway, Hyprland and niri, such as River, Wayfire and labwc, the compositor does not report where the focused window is. Hints in native apps are offset there, and --capture-scope window covers the whole screen, see wlroots compositors.
  • GNOME Wayland needs a shell extension for the focused window. X11 cannot do modifier passthrough. neru services needs systemd.
  • A source build with CGO_ENABLED=0 cannot move the cursor, click, scroll, capture keys, draw overlays or run vision, and says so once at startup. The Linux release binary is built with CGO.
  • Neither X11 nor Wayland can leave one window out of a screen share, so general.hide_overlay_in_screen_share and neru toggle-screen-share do nothing there.

Windows: one gap.

  • Vim mode reads two languages at most, the first in the account’s language list that has an OCR pack and the first Chinese, Japanese or Korean one. macOS reads every script it knows.

These are boundaries, not gaps:

  • Windows running as administrator. While an elevated app has focus, hotkeys fire and the cursor moves, but the mode sees no keys and every click, scroll and injected key is dropped. Running Neru elevated fixes this, at the cost of an admin token on a process that sees every keystroke and a UAC prompt per manual launch. The secure desktop is out of reach either way.

macOS: one gap. Insert and F21 to F24 validate but never fire, because macOS has no key code for them. They stay valid so one config works everywhere.