---

https://github.com/user-attachments/assets/f4c86753-0109-47c9-a94e-775af2546a17

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

Why Neru

• Works where accessibility trees don't. Grid modes split pixels, not widgets, so they work in canvases, games and remote desktops. Hints use the accessibility tree, on-device OCR, or a pure-Go scan of the screen image.
• Fast. The event tap sits on every keystroke, and Neru treats any added latency as a bug.
• No per-app hacks. Good defaults, plus per-app overrides you write yourself, applied when focus changes.
• Scriptable. 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. Hooks run your own steps when a mode opens or closes, the focused app changes, or Neru pauses. 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.
• Private. OCR and element detection run on-device. No telemetry, no accounts, and typed text never reaches the log.
• Fails loudly. A mistyped flag in a binding fails config validation instead of doing nothing when you press the key.

Install

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/y3owk1n/neru/main/scripts/install.sh | bash

# Windows
irm https://raw.githubusercontent.com/y3owk1n/neru/main/scripts/install.ps1 | iex

Run it again to update. Homebrew, oku, Nix, prebuilt binaries, building from source, agent skills and uninstalling are in Installation.

Quick start

Run neru launch, grant the permissions neru doctor asks for, then press Primary+Shift+Space for hints. The full first run, including Linux, is in Getting started.

Modes

Primary is Cmd on macOS and Ctrl on Linux and Windows. Linux ships without these defaults so they never collide with terminal shortcuts. Every binding is remappable.

Every mode except monitor select gives you left, right and middle click, double and triple click, drag with any button, and sticky modifiers. [held_repeat] adds held-key glide, with acceleration if you want it.

Configuration

Everything is one TOML file. Apply edits with neru config reload, or change one value with neru config set.

[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"

[modes.window.hotkeys]
"h" = "exec yabai -m window --focus west"
"l" = "exec yabai -m window --focus east"

Every hotkey command is also a shell command:

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

Themes, indicators, smooth cursor and scroll, virtual pointer, app exclusions and screen-share hiding are options too.

Build on Neru

Status bars, launchers and voice tools can follow Neru and drive it:

neru watch --event mode_enter,mode_exit   # one JSON line per mode change

neru := client.New()   // github.com/y3owk1n/neru/client
status, err := neru.Status(ctx)
_, err = neru.Send(ctx, "hints", "--action", "left_click")

Which interface fits which tool is in Build on Neru. With a coding agent, the neru-build-integration skill writes and tests one against your installed version.

Documentation

Read the docs at neru.kylewong.my, or browse docs/ here on GitHub.

Community

"neru: the ACTUAL BEST app for ditching mouse"

• Neru Dojo: a browser game to train recursive grid and hints.
• Community configs: setups shared by users.
• Discord: questions and setups.

Contributing

Bug reports, especially on Linux and Windows, and pull requests are welcome. Start with CONTRIBUTING.md.

Support the project

If Neru has earned a place in your workflow, sponsor it. Need only window management? mimi is Neru's window and space features as a standalone tool.

License

MIT. See LICENSE.