neru

module

v1.48.0 Latest Latest Go to latest Published: Jul 20, 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
Full featured ✅	Basic support 🔵	Basic support 🔵

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

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

Grant Accessibility in System Settings → Privacy & Security → Accessibility, then:

Press Cmd+Shift+Space. Labels appear. You're already using it.

Other options (Nix flake, or build from source and run just install) → Installation Guide

Pick your mode

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

_{Recursive Grid · start here}

_Grid

_{Hints (AX + Vision OCR)}

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

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

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 Guide · Configuration Guide · 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	✅	✅	✅

→ Roadmap · Cross-platform details

Documentation

Everything you need to go deep:

Guide	What's in it
Installation	Homebrew, Nix, source, permissions, launchd
CLI	Every command and flag
Configuration	Keybindings, themes, overlays, all settings
Tips & Tricks	Power-user patterns and setups
Troubleshooting	Common issues and fixes
Roadmap	What's coming
Contributing	PRs and bug reports

Contributing

Neru is written in Go and Objective-C with a clean, modular structure — adding a new feature or platform adapter is straightforward. Pull requests are very welcome.

git checkout -b feature/your-feature
just test && just lint
# open a pull request

→ Development Guide · Coding Standards

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

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
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/grid Package grid provides grid-based navigation functionality for Neru.	Package grid provides grid-based navigation functionality for Neru.
app/components/hints Package hints provides accessibility tree-based hint generation and navigation.	Package hints provides accessibility tree-based hint generation and navigation.
app/components/modeindicator Package modeindicator provides mode indicator overlay components.	Package modeindicator provides mode indicator overlay components.
app/components/overlayutil Package overlayutil provides shared utilities for overlay management.	Package overlayutil provides shared utilities for overlay management.
app/components/overlayutil/native Package native provides platform-native memory helpers for overlay operations.	Package native provides platform-native memory helpers for overlay operations.
app/components/recursivegrid Package recursivegrid provides the recursivegrid component.	Package recursivegrid provides the recursivegrid component.
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/stickyindicator Package stickyindicator provides sticky modifiers indicator overlay components.	Package stickyindicator provides sticky modifiers indicator overlay components.
app/components/systray Package systray provides the system tray icon and menu for Neru.	Package systray provides the system tray icon and menu for Neru.
app/components/virtualpointer Package virtualpointer renders a cursor-following virtual pointer overlay.	Package virtualpointer renders a cursor-following virtual pointer overlay.
app/modes Package modes implements the different operational modes for Neru.	Package modes implements the different operational modes for Neru.
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.
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.
core Package core provides the core business logic and infrastructure for Neru.	Package core provides the core business logic and infrastructure for Neru.
core/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.
core/domain/action Package action defines domain models for user actions.	Package action defines domain models for user actions.
core/domain/element Package element provides domain models for UI elements.	Package element provides domain models for UI elements.
core/domain/grid Package grid provides domain models and logic for grid-based navigation.	Package grid provides domain models and logic for grid-based navigation.
core/domain/hint Package hint provides hint generation algorithms for UI elements.	Package hint provides hint generation algorithms for UI elements.
core/domain/recursivegrid Package recursivegrid provides recursive cell-based navigation for screen coordinates.	Package recursivegrid provides recursive cell-based navigation for screen coordinates.
core/domain/state Package state provides centralized state management for the Neru application.	Package state provides centralized state management for the Neru application.
core/errors Package derrors provides domain-specific error types and utilities.	Package derrors provides domain-specific error types and utilities.
core/infra/accessibility Package accessibility implements ports.AccessibilityPort, providing access to platform UI elements (clickable nodes, focused app, element trees).	Package accessibility implements ports.AccessibilityPort, providing access to platform UI elements (clickable nodes, focused app, element trees).
core/infra/apptrace Package apptrace provides tracing utilities.	Package apptrace provides tracing utilities.
core/infra/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.
core/infra/config Package config provides configuration management implementation.	Package config provides configuration management implementation.
core/infra/electron Package electron provides enhanced accessibility support for Electron, Chromium, and Firefox-based applications that don't expose full accessibility information by default.	Package electron provides enhanced accessibility support for Electron, Chromium, and Firefox-based applications that don't expose full accessibility information by default.
core/infra/eventtap Package eventtap for EventTap adapter.	Package eventtap for EventTap adapter.
core/infra/hotkeys Package hotkeys provides comprehensive functionality for registering and handling global hotkeys in the Neru application using per-hotkey CGEventTaps, enabling system-wide keyboard shortcuts.	Package hotkeys provides comprehensive functionality for registering and handling global hotkeys in the Neru application using per-hotkey CGEventTaps, enabling system-wide keyboard shortcuts.
core/infra/ipc Package ipc implements the IPC adapter.	Package ipc implements the IPC adapter.
core/infra/keyfeed Package keyfeed posts keyboard input directly to the host operating system.	Package keyfeed posts keyboard input directly to the host operating system.
core/infra/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.
core/infra/overlay Package overlay provides an adapter for the UI overlay system.	Package overlay provides an adapter for the UI overlay system.
core/infra/platform Package platform provides a factory for platform-specific infrastructure components.	Package platform provides a factory for platform-specific infrastructure components.
core/infra/platform/darwin Package darwin provides macOS-specific platform implementations.	Package darwin provides macOS-specific platform implementations.
core/infra/platform/linux Package linux compiles native C bridge sources (.c) in this directory.	Package linux compiles native C bridge sources (.c) in this directory.
core/infra/platform/linux/wlr_protocol Package wlr_protocol compiles the wayland-scanner generated protocol implementation files (.c) exactly once.	Package wlr_protocol compiles the wayland-scanner generated protocol implementation files (.c) exactly once.
core/infra/platform/windows Package windows provides Windows-specific implementations of infrastructure components.	Package windows provides Windows-specific implementations of infrastructure components.
core/infra/systray Package systray provides the system tray menu implementation.	Package systray provides the system tray menu implementation.
core/infra/textinput Package textinput provides an adapter and stub for native text input.	Package textinput provides an adapter and stub for native text input.
core/infra/vision Package vision provides vision-based element detection using the macOS Vision Framework.	Package vision provides vision-based element detection using the macOS Vision Framework.
core/ports Package ports defines interfaces for external dependencies.	Package ports defines interfaces for external dependencies.
core/ports/mocks Package mocks provides mock implementations of port interfaces for testing.	Package mocks provides mock implementations of port interfaces for testing.
ui Package ui implements the user interface components for the Neru application.	Package ui implements the user interface components for the Neru application.
ui/coordinates Package coordinates provides coordinate conversion and transformation utilities for Neru.	Package coordinates provides coordinate conversion and transformation utilities for Neru.
ui/overlay Package overlay provides overlay functionality for the Neru application.	Package overlay provides overlay functionality for the Neru application.