neru

module

v1.50.0 Latest Latest Go to latest Published: Aug 4, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/y3owk1n/neru

Links

Open Source Insights

README ¶

Neru

Navigate your entire screen without touching the mouse.

Built for the person who already remapped Caps Lock.

Free and open-source. No subscription. No trial. No catch.

macOS	Linux	Windows
Stable ✅	Beta — daily 🔵	Alpha — try it 🟡

_{What these mean — stable is fully featured, beta is good for daily driving, alpha is worth trying but not yet worth switching to.}

If you use Vimium in the browser, you already know what this feels like. Neru brings that to your entire operating system — every app, every window, every menu bar item. Navigate with labels, grids, or vim-style keys. Click, right-click, drag, scroll, select text — all without leaving your keyboard.

Here's the whole flow:

Cmd+Shift+Space   →  labels appear on every clickable element
type the label    →  cursor jumps there
Shift+L           →  left click

The mouse is now optional.

Unlike most tools in this space, Neru is CLI-first — every action is a command, every setting is a plain toml file, everything is scriptable. No settings panel. No GUI preferences window. It lives in your dotfiles like it was always supposed to be there.

See it in action — recursive grid mode in real use:

https://github.com/user-attachments/assets/6b5673e1-7131-4bc0-ad57-41678e9423b9

Install

macOS — Homebrew (recommended):

brew tap y3owk1n/tap
brew install --cask y3owk1n/tap/neru

All platforms — prebuilt binaries

Download the latest release for your OS from GitHub Releases:

Platform	Architecture	File
macOS	Intel (x86_64)	`neru-darwin-amd64.zip`
macOS	Apple Silicon (arm64)	`neru-darwin-arm64.zip`
Linux	x86_64	`neru-linux-amd64.zip`
Linux	ARM64	`neru-linux-arm64.zip`
Windows	x86_64	`neru-windows-amd64.zip`
Windows	ARM64	`neru-windows-arm64.zip`

Extract the binary or executable and place it on your PATH.

Linux — Nix flake

Add to your flake inputs, then enable the module:

services.neru.enable = true;

See Installation Guide for nix-darwin, NixOS, and home-manager examples.

From source

git clone https://github.com/y3owk1n/neru.git && cd neru
just build   # or just bundle on macOS
just install

Once you're done with the installation, you can just run the Neru.app (macOS) or the neru launch binary (macOS / Linux / Windows). On Windows you can also start Neru from the Start Menu, which runs the same neru.exe without a console window. Neru will prompt for config initialization and accessibility permission whenever is needed.

Pick your mode

Five modes, one tool — mix and match as the situation calls for it.

_{Recursive Grid · start here}

_Grid

_{Hints (AX + Vision OCR)}

Mode	Default hotkey	How it works	Best for
Recursive Grid ⭐	`Primary+Shift+C`	Divides screen into cells; narrow down with home-row keys	Everything — any app, canvas, or game
Hints	`Primary+Shift+Space`	Labels every clickable element via Accessibility API or Vision OCR	Native apps, Electron (VS Code, Slack), Figma
Grid	`Primary+Shift+G`	Jump directly to a cell by row + column label	Fast coarse movement across large monitors
Scroll	`Primary+Shift+S`	Vim-style `j`/`k` scrolling, `u`/`d` for half pages	Reading docs and code without lifting your hands
Monitor Select	unbound	Labels each display; type a label to jump the cursor there	Multi-monitor setups

Primary is Cmd on macOS and Ctrl on Linux and Windows. Monitor Select ships without a default binding — bind monitor_select to any key you like.

On Linux there are no default global hotkeys. They are cleared at startup to avoid colliding with terminal and desktop shortcuts such as Ctrl+Shift+C. Bind the modes yourself in [hotkeys], or in your compositor — see Global hotkeys on Linux.

All bindings are fully remappable — Colemak, Dvorak, whatever you're on. → Configuration Reference

CLI-first, by design

Most tools in this space are GUI apps with a settings panel. Neru is the opposite — the CLI is the interface, and config is a file you own.

neru hints          # trigger hints mode
neru grid           # trigger grid mode
neru recursive_grid # trigger recursive grid mode
neru scroll         # trigger scroll mode
neru config reload  # hot-reload config without restarting
neru status         # check daemon state and permissions

Config lives at ~/.config/neru/config.toml — plain text, version-controllable, and hot-reloadable. Every action is available over IPC, so Neru composes naturally with skhd, Raycast, Alfred, Hammerspoon, or any shell script. If it can run a command, it can drive Neru.

neru config init      # generate a fully-commented starter config
neru config validate  # check for errors before applying
neru config reload    # apply changes without restarting

→ CLI Reference · Configuration Reference · Config Showcases

What people are saying

"neru: the ACTUAL BEST app for ditching mouse"

Watch the author run their entire daily workflow without touching the mouse → HOW-I-USE-NERU.md

Got questions or want to share your setup? Join the Discord →

Neru Dojo — build your muscle memory 🥋

The community built a browser-based training game to help you get fast with recursive grid and hints. Practice target acquisition, sharpen your reaction time, get reps in before it clicks.

👉 Play Neru Dojo — no install, works in any browser.

https://github.com/user-attachments/assets/d99328a6-b5f9-402a-a01b-297da2ffb454

How Neru compares

Tool	Approach	Price	Open Source
Neru	Grid + Recursive Grid + AX Hints + Vision OCR	Free	✅
Homerow	AX-Tree Hints	Paid	❌
Wooshy	AX-Tree Search-to-click	Paid	❌
Mouseless	Grid pointer control	Paid	❌
Scoot	AX Hints + Grid	Free	✅
Glyphlow	Hints + vim text editing	Free	✅
Stochos	Keyboard driven mouse control	Free	✅
warpd	Grid + Hints + Normal Pointer	Free	✅
Mousemaster	Grid + Hints + Continuous Pointer + Key Remapping	Free	✅
Vimac	AX Hints	Free	✅ (unmaintained)

More modes, more engines, more platforms — and it's free. If you've been paying for any of the tools above, Neru is worth 10 minutes of your time.

Platform support

Capability	macOS	Linux	Windows
Recursive Grid	✅	✅	✅
Grid	✅	✅	✅
Vim-Style Scroll	✅	✅	✅
Hints (Accessibility API)	✅	🔵	🔵
Hints (Vision OCR)	✅	🔲	🔲
Direct Mouse Injection	✅	✅	✅
Global Hotkeys	✅	✅	✅
Native Overlays	✅	✅	✅
Monitor Select	✅	✅	🔲

✅ full · 🔵 works with limits · 🔲 not available

Hints caveats. On Linux, hints work through AT-SPI, so coverage depends on the app exposing an accessibility tree (GTK/Qt do; Chromium and Electron apps need --force-renderer-accessibility). On Windows, UI Automation coverage is initial and the tree walk is shallow, and per-app config does not re-apply when you change windows. Linux requires X11 or Wayland on wlroots/KWin — GNOME Wayland is not supported; use a GNOME X11 session.

→ Roadmap · Cross-platform details

Documentation

Everything you need to go deep:

Using Neru

Guide	What's in it
Installation	Homebrew, Nix, prebuilt binaries, source, permissions
CLI Reference	Every command, flag, and argument
Configuration Reference	Every option, with types, defaults, and platform support
Tips & Tricks	Worked configuration recipes
Config Showcases	Real setups shared by the community
Troubleshooting	Common issues and fixes

Platform support

Guide	What's in it
Cross-Platform Guide	What works on each platform, and how it is implemented
Linux Setup	Dependencies, permissions, building, deployment
Linux Desktops	Per-desktop setup, protocol support, and known issues

Working on Neru

Guide	What's in it
Contributing	How to propose, commit, and land a change
Development Guide	Setup, building, testing, debugging, where code goes
Architecture	Layers, boundaries, data flow, platform isolation
Agent Guide	Conventions and contracts, for humans and AI agents
Roadmap	What's coming next

Contributing

Neru is written in Go and Objective-C with a hexagonal architecture whose rules are executable: the guardrail tests in internal/architecture/ pin the layering, platform isolation, port/mock parity, and even doc-link integrity — each with a comment explaining the real bug it prevents. If you break a rule, the failure message tells you how to fix it. Adding a feature or platform adapter is straightforward, and pull requests are very welcome.

git checkout -b feature/your-feature
just ci   # everything CI checks, locally
# open a pull request

→ Contributing Guide · Development Guide · Good first issues

Support the project

Neru is built and maintained by one person, entirely in spare time. If it's earned a place in your workflow, a sponsorship goes a long way:

👉 GitHub Sponsors

Just need window management?

mimi grew out of this project — it's the window and space management pieces extracted into a standalone tool, for when neru is more than you need.

brew install --cask y3owk1n/tap/mimi

→ github.com/y3owk1n/mimi

License

MIT — see LICENSE.

Stop reaching for the mouse. It takes one command.

brew install --cask y3owk1n/tap/neru  # macOS
# or download a binary: github.com/y3owk1n/neru/releases/latest

Welcome to the mouseless life.

Made with ❤️ by y3owk1n

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
genman command Package main is the main entry point for the genman command.	Package main is the main entry point for the genman command.
neru command Package main is the entry point for the Neru application.	Package main is the entry point for the Neru application.
configs Package configs provides embedded configuration files.	Package configs provides embedded configuration files.
internal
adapter/accessibility Package accessibility implements ports.AccessibilityPort: finding clickable elements, identifying the focused application, and walking element trees.	Package accessibility implements ports.AccessibilityPort: finding clickable elements, identifying the focused application, and walking element trees.
adapter/accessibility/atspi Package atspi is the Linux accessibility backend.	Package atspi is the Linux accessibility backend.
adapter/accessibility/ax Package ax is the contract every accessibility backend implements.	Package ax is the contract every accessibility backend implements.
adapter/accessibility/native Package native is the accessibility client built on each OS's own API.	Package native is the accessibility client built on each OS's own API.
adapter/accessibility/native/darwin Package darwin reads the accessibility tree through AXUIElement.	Package darwin reads the accessibility tree through AXUIElement.
adapter/accessibility/native/linux Package linux supplies the Linux element and geometry layer.	Package linux supplies the Linux element and geometry layer.
adapter/accessibility/native/windows Package windows reads the accessibility tree through UI Automation over COM.	Package windows reads the accessibility tree through UI Automation over COM.
adapter/appwatcher Package appwatcher monitors application lifecycle events (launch, terminate, activate, deactivate, screen change) and dispatches them to registered callbacks.	Package appwatcher monitors application lifecycle events (launch, terminate, activate, deactivate, screen change) and dispatches them to registered callbacks.
adapter/eventtap Package eventtap implements ports.EventTapPort over the platform keyboard capture backends.	Package eventtap implements ports.EventTapPort over the platform keyboard capture backends.
adapter/eventtap/darwin Package darwin captures keys through a Quartz CGEventTap.	Package darwin captures keys through a Quartz CGEventTap.
adapter/eventtap/linux Package linux captures keys on Linux, and owns the Wayland global-hotkey listener and the uinput scroll device that go with it.	Package linux captures keys on Linux, and owns the Wayland global-hotkey listener and the uinput scroll device that go with it.
adapter/eventtap/tap Package tap is the contract every event-tap backend implements.	Package tap is the contract every event-tap backend implements.
adapter/eventtap/windows Package windows captures keys through a low-level WH_KEYBOARD_LL hook.	Package windows captures keys through a low-level WH_KEYBOARD_LL hook.
adapter/hotkeys Package hotkeys registers global keyboard shortcuts.	Package hotkeys registers global keyboard shortcuts.
adapter/hotkeys/darwin Package darwin registers global hotkeys on darwin.	Package darwin registers global hotkeys on darwin.
adapter/hotkeys/linux Package linux registers global hotkeys on linux.	Package linux registers global hotkeys on linux.
adapter/hotkeys/windows Package windows registers global hotkeys on windows.	Package windows registers global hotkeys on windows.
adapter/ipc Package ipc implements the IPC adapter.	Package ipc implements the IPC adapter.
adapter/keyfeed Package keyfeed posts keyboard input directly to the host operating system.	Package keyfeed posts keyboard input directly to the host operating system.
adapter/logger Package logger provides comprehensive structured logging functionality for the Neru application, using the zap logging library with file rotation support to ensure reliable and efficient logging.	Package logger provides comprehensive structured logging functionality for the Neru application, using the zap logging library with file rotation support to ensure reliable and efficient logging.
adapter/overlay Package overlay implements ports.OverlayPort over the platform overlay backends.	Package overlay implements ports.OverlayPort over the platform overlay backends.
adapter/overlay/darwin Package darwin draws the overlay with Cocoa.	Package darwin draws the overlay with Cocoa.
adapter/overlay/linux Package linux draws the overlay on X11 and Wayland.	Package linux draws the overlay on X11 and Wayland.
adapter/overlay/manager Package manager is the overlay window management contract, a leaf both the backends and the backend selector depend on.	Package manager is the overlay window management contract, a leaf both the backends and the backend selector depend on.
adapter/overlay/render/badge Package badge holds the platform-neutral geometry and color math shared by the overlay badge renderers: indicator badges, hint labels and grid text backgrounds all size themselves from the same font-based estimates and read colors from the same hex notation.	Package badge holds the platform-neutral geometry and color math shared by the overlay badge renderers: indicator badges, hint labels and grid text backgrounds all size themselves from the same font-based estimates and read colors from the same hex notation.
adapter/overlay/render/grid Package grid provides grid-based navigation functionality for Neru.	Package grid provides grid-based navigation functionality for Neru.
adapter/overlay/render/hints Package hints provides accessibility tree-based hint generation and navigation.	Package hints provides accessibility tree-based hint generation and navigation.
adapter/overlay/render/modeindicator Package modeindicator renders the small on-screen badge naming the active mode.	Package modeindicator renders the small on-screen badge naming the active mode.
adapter/overlay/render/overlayutil Package overlayutil provides shared utilities for overlay management.	Package overlayutil provides shared utilities for overlay management.
adapter/overlay/render/overlayutil/native Package native provides platform-native memory helpers for overlay operations.	Package native provides platform-native memory helpers for overlay operations.
adapter/overlay/render/recursivegrid Package recursivegrid renders the recursive-grid overlay: the nested cells and their key labels that let a selection be refined one level at a time.	Package recursivegrid renders the recursive-grid overlay: the nested cells and their key labels that let a selection be refined one level at a time.
adapter/overlay/render/stickyindicator Package stickyindicator renders the badge showing which modifiers are currently held sticky.	Package stickyindicator renders the badge showing which modifiers are currently held sticky.
adapter/overlay/render/virtualpointer Package virtualpointer renders a cursor-following virtual pointer overlay.	Package virtualpointer renders a cursor-following virtual pointer overlay.
adapter/overlay/windows Package windows draws the overlay with GDI on a layered window.	Package windows draws the overlay with GDI on a layered window.
adapter/platform Package platform selects and constructs the per-OS implementations of the core ports — the only place that decides which adapter a build gets.	Package platform selects and constructs the per-OS implementations of the core ports — the only place that decides which adapter a build gets.
adapter/platform/darwin Package darwin provides macOS-specific platform implementations.	Package darwin provides macOS-specific platform implementations.
adapter/platform/linux Package linux implements ports.SystemPort for the X11, wlroots-Wayland and KDE-Wayland backends, plus the cgo bridge for the native C sources here.	Package linux implements ports.SystemPort for the X11, wlroots-Wayland and KDE-Wayland backends, plus the cgo bridge for the native C sources here.
adapter/platform/linux/wlr_protocol Package wlr_protocol compiles the wayland-scanner generated .c files exactly once; `just generate-all-protocols` regenerates them from protocol/*.xml.	Package wlr_protocol compiles the wayland-scanner generated .c files exactly once; `just generate-all-protocols` regenerates them from protocol/*.xml.
adapter/platform/mousestate Package mousestate tracks which mouse buttons Neru is currently holding down.	Package mousestate tracks which mouse buttons Neru is currently holding down.
adapter/platform/windows Package windows implements ports.SystemPort over pure-Go Win32 bindings, no cgo: monitor enumeration, SendInput, the WH_KEYBOARD_LL hook, RegisterHotKey, GDI layered-window overlays, dark-mode via the registry.	Package windows implements ports.SystemPort over pure-Go Win32 bindings, no cgo: monitor enumeration, SendInput, the WH_KEYBOARD_LL hook, RegisterHotKey, GDI layered-window overlays, dark-mode via the registry.
adapter/systray Package systray implements ports.SystrayPort over the platform tray backends: darwin (NSStatusItem via cgo), linux (D-Bus StatusNotifierItem with dbusmenu), windows (Shell_NotifyIcon).	Package systray implements ports.SystrayPort over the platform tray backends: darwin (NSStatusItem via cgo), linux (D-Bus StatusNotifierItem with dbusmenu), windows (Shell_NotifyIcon).
adapter/systray/darwin Package darwin drives the darwin system tray.	Package darwin drives the darwin system tray.
adapter/systray/icon Package icon holds the tray icon bytes.	Package icon holds the tray icon bytes.
adapter/systray/linux Package linux drives the linux system tray.	Package linux drives the linux system tray.
adapter/systray/windows Package windows drives the windows system tray.	Package windows drives the windows system tray.
adapter/textinput Package textinput implements ports.TextInputPort, the native text field used by hint search.	Package textinput implements ports.TextInputPort, the native text field used by hint search.
adapter/vision Package vision implements ports.VisionPort, OCR-based element detection for hints, backed by the macOS Vision framework.	Package vision implements ports.VisionPort, OCR-based element detection for hints, backed by the macOS Vision framework.
app Package app contains the main application logic for Neru.	Package app contains the main application logic for Neru.
app/components Package components provides feature-specific implementations.	Package components provides feature-specific implementations.
app/components/scroll Package scroll provides Vim-style scrolling functionality for the Neru application.	Package scroll provides Vim-style scrolling functionality for the Neru application.
app/components/systray Package systray defines Neru's tray menu: which entries exist, what they say, and what each does.	Package systray defines Neru's tray menu: which entries exist, what they say, and what each does.
app/heldrepeat Package heldrepeat drives the repeat-while-held loop shared by both hotkey paths.	Package heldrepeat drives the repeat-while-held loop shared by both hotkey paths.
app/ipcctrl Package ipcctrl routes IPC commands to application behavior — the daemon side of the protocol whose transport lives in internal/adapter/ipc.	Package ipcctrl routes IPC commands to application behavior — the daemon side of the protocol whose transport lives in internal/adapter/ipc.
app/keybinding Package keybinding binds keys to action sequences.	Package keybinding binds keys to action sequences.
app/modes Package modes implements the different operational modes for Neru.	Package modes implements the different operational modes for Neru.
app/render Package render is the app-layer rendering facade: it owns the OverlayRenderer that translates mode state into calls on the overlay manager and the shared render styles.	Package render is the app-layer rendering facade: it owns the OverlayRenderer that translates mode state into calls on the overlay manager and the shared render styles.
app/sequence Package sequence runs action sequences: ordered steps that may be an action, a shell command, a mode name, or a macro expanding to another sequence.	Package sequence runs action sequences: ordered steps that may be an action, a shell command, a mode name, or a macro expanding to another sequence.
app/services Package services implements application use cases and orchestration logic.	Package services implements application use cases and orchestration logic.
app/services/modeindicator Package modeindicator provides the mode indicator service.	Package modeindicator provides the mode indicator service.
app/services/stickyindicator Package stickyindicator provides the sticky modifiers indicator service.	Package stickyindicator provides the sticky modifiers indicator service.
architecture Package architecture holds the guardrail tests that keep the codebase's shape honest.	Package architecture holds the guardrail tests that keep the codebase's shape honest.
buildinfo Package buildinfo holds the build-stamped identity of the binary.	Package buildinfo holds the build-stamped identity of the binary.
cli Package cli provides the command-line interface for the Neru application.	Package cli provides the command-line interface for the Neru application.
cli/cliutil Package cliutil provides shared utilities for CLI command implementations.	Package cliutil provides shared utilities for CLI command implementations.
config Package config provides comprehensive configuration management for the Neru application.	Package config provides comprehensive configuration management for the Neru application.
config/loader Package loader owns the runtime half of configuration: locating and decoding the TOML file, merging user hotkeys over the platform defaults, validating the result, hot-reload watching, persistence of overrides, and the reflection-based field access behind `neru config set`.	Package loader owns the runtime half of configuration: locating and decoding the TOML file, merging user hotkeys over the platform defaults, validating the result, hot-reload watching, persistence of overrides, and the reflection-based field access behind `neru config set`.
derrors Package derrors provides domain-specific error types and utilities.	Package derrors provides domain-specific error types and utilities.
domain Package domain defines the core domain models, constants, and shared types for the Neru application.	Package domain defines the core domain models, constants, and shared types for the Neru application.
domain/action Package action defines domain models for user actions.	Package action defines domain models for user actions.
domain/element Package element provides domain models for UI elements.	Package element provides domain models for UI elements.
domain/geometry Package geometry provides coordinate conversion and transformation utilities for Neru.	Package geometry provides coordinate conversion and transformation utilities for Neru.
domain/grid Package grid provides domain models and logic for grid-based navigation.	Package grid provides domain models and logic for grid-based navigation.
domain/hint Package hint provides hint generation algorithms for UI elements.	Package hint provides hint generation algorithms for UI elements.
domain/keyvocab Package keyvocab owns the key and modifier vocabulary shared between the event-tap backends and the mode handler: canonical key and modifier spellings, and the synthetic "__keyup_"/"__modifier_" wire events the taps emit and the modes consume.	Package keyvocab owns the key and modifier vocabulary shared between the event-tap backends and the mode handler: canonical key and modifier spellings, and the synthetic "__keyup_"/"__modifier_" wire events the taps emit and the modes consume.
domain/modeflag Package modeflag is the flag vocabulary the mode commands are written in.	Package modeflag is the flag vocabulary the mode commands are written in.
domain/recursivegrid Package recursivegrid divides the screen into a grid and narrows the active area with every cell the user selects, until the cell is too small to divide or the depth limit is hit.	Package recursivegrid divides the screen into a grid and narrows the active area with every cell the user selects, until the cell is too small to divide or the depth limit is hit.
domain/state Package state provides centralized state management for the Neru application.	Package state provides centralized state management for the Neru application.
ports Package ports defines interfaces for external dependencies.	Package ports defines interfaces for external dependencies.
ports/mocks Package mocks provides mock implementations of port interfaces for testing.	Package mocks provides mock implementations of port interfaces for testing.