Neru: Vimium keys for the whole desktop, in one Go binary and one TOML file

The browser extension idea, applied to the whole screen

Neru does what Vimium does in the browser, for every app, window, menu bar and dock item on your screen. The interaction is a hotkey, then the label of the element you want, and the cursor jumps there and clicks.

The pitch is one line: hints, grids and vim keys for your whole desktop, free, open source, one binary, one TOML file. The platform table gives the state of play honestly, with macOS 14 and above marked stable, and Linux on X11 and Wayland plus Windows 10 and above marked as beta with daily builds. The README links a page explaining what those labels mean, which is a good sign for a project that has a non-trivial platform story.

The topics list gives a hint about the audience: accessibility, keyboard navigation, homerow, mouseless, OCR, and the names of the tools it positions against, including Vimium, Warp and Wayland. This is a tool for someone who already navigates by keyboard and wants that to work everywhere, rather than a general accessibility tool.

The repository is a Go module with the client/, cmd/, internal/, protocol/, schemas/, configs/ and resources/ directories, a website/ directory, Nix and oku packaging files, an AGENTS.md and a CONTEXT.md, and a justfile as the build entry point.

Grids split pixels, which is why they work in canvases and games

The first of the reasons to use Neru is the one that decides the whole design. It works where accessibility trees do not. Grid modes split pixels, not widgets, so they work in canvases, in games and in remote desktops. Hints use the accessibility tree, on-device OCR, or a pure-Go scan of the screen image.

Three different strategies, and the choice is what makes the tool usable in places where a normal accessibility-driven tool stops. A native app exposes its widgets, so the accessibility tree gives you clean labels. A canvas or a game exposes nothing, so a pixel scan is the only option, and OCR reads the text off the screen image. A remote desktop renders pixels, so the same path applies.

The pure-Go scan is worth noting on its own. It means the image analysis does not require a separate native OCR engine, and the README says OCR and element detection run on-device, with no telemetry, no accounts, and typed text never reaching the log. For a tool that sees everything you type, that last sentence is the important one.

The modes are the visible form of this. Recursive Grid splits 3x3 and lets you pick a cell after cell until the cursor lands, and it is marked as working for anything including canvases and games. Bisect does the same with keys, where hjkl keeps a half and yubn keeps a quadrant, so nothing has to be read. Hints labels every target through the accessibility tree, OCR or a pixel scan, which suits native apps, Electron, browsers and Figma. Grid types a row and column label for coarse jumps on a big monitor. Scroll gives j and k, u and d, gg and G, and h and l in any scroll view, for reading without lifting your hands. Monitor Select labels each display so you can jump to one, and it is unbound by default.

The hotkeys are named after the Primary modifier, and Linux ships without them

Every mode has a default hotkey, and they are listed in the modes table. Recursive Grid is Primary+Shift+C, Bisect is Primary+Shift+B, Hints is Primary+Shift+Space, Grid is Primary+Shift+G and Scroll is Primary+Shift+S. Monitor Select is disabled and unbound, and the Your own row is the escape hatch for a mode you declare yourself.

Primary is Cmd on macOS and Ctrl on Linux and Windows, and the README explains a decision that tells you a lot about the author: Linux ships without these defaults so they never collide with terminal shortcuts. On Linux, the choice is left to you rather than imposed.

Every binding is remappable, and every mode except monitor select gives you left, right and middle click, double and triple click, drag with any button, and sticky modifiers. There is also a held_repeat option that adds held-key glide, with acceleration if you want it.

One more of the design principles is stated as a feature and deserves to be taken literally: Neru fails loudly. A mistyped flag in a binding fails config validation instead of doing nothing when you press the key. For a tool driven by muscle memory, a binding that silently does nothing is worse than one that refuses to start.

Everything is one TOML file, and every command is also a shell command

The configuration is a single TOML file, edited with neru config reload, or changed one value at a time with neru config set. The file covers hotkeys, macros, per-app overrides and mode settings, and the example in the README shows all four:

[hotkeys]
"Primary+Shift+Space" = "hints --action left_click"   # click on select, Vimium style
"Primary+Shift+W" = "mode window"

[macros]
click_and_exit = ["action left_click --bail-on-error", "idle"]

[[hints.app_configs]]
bundle_id = "com.brave.Browser"   # bundle ID on macOS, WM_CLASS or app_id on Linux, exe path on Windows
hotkeys = { "Return" = "macro click_and_exit" }

[modes.window]
indicator = "Window"

The per-app override mechanism is the interesting part, and the comment on the bundle_id line spells out the platform differences: bundle ID on macOS, WM_CLASS or app_id on Linux, and the executable path on Windows. The README's description is that there are no per-app hacks, just good defaults plus per-app overrides you write yourself, applied when focus changes.

The commands themselves are plain executables, which means a binding can be typed in a shell:

neru hints --role button --text save   # only buttons whose text matches
neru run "action save_cursor_pos" "hints --action left_click" \
         "action wait_for_mode_exit" "action restore_cursor_pos"
neru config set hints.strategy contour
neru doctor                            # diagnose permissions and backends

The neru run example is a sequence of actions, saving the cursor position, doing a click and restoring the position afterwards, which is how you script an interaction rather than just trigger one.

Hotkeys, the CLI and the IPC socket run the same commands

The scriptability claim in the README is specific: hotkeys, the neru CLI and the IPC socket run the same commands, so a binding works unchanged from skhd, Hammerspoon, Raycast or a shell script. That is a design decision with a consequence. Your automation layer does not need a separate Neru specific API, because the thing you bind is a command, and that command is the same one the CLI takes.

Hooks extend the same idea. They run your own steps when a mode opens or closes, when the focused app changes, or when Neru pauses. So a window manager integration is a hook rather than a plugin, and the README's configuration example shows a mode named window whose hotkeys are exec yabai -m window --focus west and the matching east command.

The observation interface is equally scriptable. neru watch streams the same events live, filtered with --event, neru query reports displays, the cursor and hint targets, and --json on the status and query commands gives a program something to parse.

The IPC protocol is versioned, with JSON schemas and a Go client package, and the repository has protocol/ and schemas/ directories for it plus client/ for that package. A versioned protocol with schemas is the difference between a socket you can script against and a socket you have to read the source of.

One Go binary, cgo where the platform demands it

Neru is a Go program, and the module is pinned tightly: go 1.26.5 with toolchain go1.26.6. The dependency list is short and tells you the shape of the thing, with cobra and pflag for the command line, BurntSushi/toml for the configuration file, zap for logging, lumberjack for log rotation, uuid, testify for tests, goleak to catch goroutine leaks, and the platform specific ones: go-winio and go-winres for Windows, godbus for D-Bus on Linux, and the clipboard package.

The build is done with a justfile, and the comments in it explain the awkward parts. The macOS deployment target is 14.0, which is why the platform table says macOS 14 and above. Version information is injected at link time into an internal buildinfo package, with the version taken from git describe, the commit from git rev-parse and the build date in UTC.

CGO is enabled on macOS and Linux, where it is required for the Objective-C bridge and for the native X11 and Wayland backends, and disabled on Windows. There is a specific workaround in the file: pipewire's libspa-0.2.pc carries -fno-strict-overflow on newer distributions such as Ubuntu 26.04, and cgo refuses a pkg-config flag it does not know, so every Linux build fails there without setting CGO_CFLAGS_ALLOW to allow that flag. The flag does nothing on other systems.

Windows gets a console subsystem binary on purpose, without the -H windowsgui flag, so that a single neru.exe serves as both the CLI and the daemon.

Where Neru is the wrong tool

The first wrong fit is a locked-down or shared machine. Neru needs an event tap on every keystroke, screen capture for the pixel scan, and the permissions that neru doctor asks for when you run neru launch. On a corporate laptop with screen recording restrictions, or on a machine where you do not have administrator rights, the tool does not function, and the permissions prompt is itself a risk that a security team will not approve.

The second is a remote desktop as the only environment. Neru is built to work over a remote desktop because it splits pixels, which is the right approach for that case, but the latency of the round trip is the constraint. Each mode change, each label selection and each click goes through the wire.

The third is a workflow that is not mouse-heavy. If you already use a tiling window manager, a command palette and a terminal, Neru overlaps with tools you have, and the marginal gain is smaller than the setup cost of learning seven modes, a TOML file and a key table.

The fourth is a platform where you need stability today. The README's own table says macOS 14 and above is stable, while Linux on X11 and Wayland and Windows 10 and above are beta with daily builds. Daily betas on two of three platforms is a fine thing to try and a poor thing to depend on, and the version numbers tell the same story: v1.58.0 on 2026-10-12 and v1.59.0 on 2026-10-19, with the last push to the repository on 2026-10-19.

And the licence deserves a sentence of its own. The project is MIT licensed with the LICENSE file at the root of the repository, which is permissive and easy to live with, and the version map in the wiki plus the per-platform support page are where you should check what a given release actually covers.

Editorial conclusion

Neru fits a keyboard-first user who wants a browser extension like Vimium to reach the entire operating system, and who is willing to grant the accessibility permissions it asks for on a machine they control. It does not fit a shared or locked-down workstation, since it needs an event tap and screen capture, and on Linux and Windows it is still a daily beta. Before adopting it, run neru doctor and neru launch on the platform you care about, since the backends differ per platform.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. y3owk1n/neru on GitHub