neru

module

v1.39.0 Latest Latest Go to latest Published: May 24, 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.

Go Version

Neru (練る — "to refine through practice") puts your cursor anywhere on screen using only your keyboard. Click, scroll, drag — all without leaving the home row.

It's a free, open-source alternative to Homerow, Mouseless, and Wooshy. No paywalls, no subscriptions, fully configurable.

See how the author uses Neru day-to-day → HOW-I-USE-NERU.md and a quick demo with recursive_grid with my own config:

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

_{Recursive Grid · recommended}

_Grid

_Hints

Mode	How it works	Best for
Recursive Grid ⭐	Divide screen into cells, narrow recursively with `u`/`i`/`j`/`k`	Everything — works in any app, any window
Grid	Coordinate grid, jump by row + column label	Quick, coarse navigation
Hints	Labels appear on every clickable UI element	Standard macOS apps with accessibility support
Scroll	Vim-style `j`/`k`, `gg`/`G`, `d`/`u`	Scrolling without lifting your hands

Recursive Grid is the recommended daily driver. It's precise, predictable, and requires no per-app setup — it just works everywhere.

Features

All mouse actions — left, right, and middle click; drag & drop; all key-bound
Sticky modifiers — tap Shift or Cmd once to apply to your next click, no holding
Per-app exclusions — opt specific apps out by bundle ID
CLI & scripting — full IPC-based CLI for shell scripts and hotkey managers
TOML config — every keybinding, color, and behavior in one file you can version-control

Works in native macOS apps, Electron apps (VS Code, Slack, Obsidian), all major browsers, creative tools (Figma, Illustrator), and system UI (Dock, Menubar, Mission Control). Grid and Recursive Grid need no accessibility support — they work universally.

Installation

macOS (Homebrew — recommended):

[!NOTE] The homebrew tap is maintained in another repo: y3owk1n/homebrew-tap If there's a problem with the tap, please open an issue in that repo or even better, a PR.

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

macOS / Linux (Nix Flake):

# inputs.neru.url = "github:y3owk1n/neru";
# Modules: nix-darwin (macOS) · nixosModules (Linux) · home-manager (both)
# See docs/INSTALLATION.md for full setup

From source (any platform):

git clone https://github.com/y3owk1n/neru.git
cd neru && just release

Post-install (macOS): grant accessibility access — System Settings → Privacy & Security → Accessibility → enable Neru.

open -a Neru              # launch
neru services install     # auto-start on login (use this only if you're not using nix with launchagents enabled)

Post-install (Linux): see Linux Setup → for display-server requirements and permissions.

neru launch               # launch

Full walkthrough: Installation Guide →

Default hotkeys

Hotkey	Action
`Cmd+Shift+C`	Recursive Grid ⭐
`Cmd+Shift+G`	Grid
`Cmd+Shift+Space`	Hints
`Cmd+Shift+S`	Scroll
`Shift+L`	Left click
`Shift+R`	Right click

All hotkeys are remappable. See Configuration Reference →

Configuration

Everything lives in ~/.config/neru/config.toml — one file, plain text, dotfile-friendly.

neru config init      # generate a commented starter config
neru config validate  # check for errors
neru config reload    # hot-reload into a running daemon

Version-control it, share it, script against it. No settings GUI, no hidden state.

Full reference: Configuration Docs → · Community configs: Config Showcases →

How Neru compares

macOS

Tool	Approach	Price	Open Source
Neru	Hints + Grid + Recursive Grid + Scroll	Free	✅
Homerow	Hints (fuzzy search + labels)	Paid	❌
Wooshy	Hints (search-to-click)	Paid	❌
Mouseless	Grid-based pointer control	Paid	❌
Scoot	Hints + Grid + Freestyle	Free	✅
Vimac	Hints + Grid	Free	✅ ⚠️ unmaintained
warpd	Hints + Grid + Normal	Free	✅ ⚠️ low activity
Shortcat	Hints (fuzzy search)	Free	❌ discontinued
Glyphlow	Hints + vim text editing	Free	✅

Browser extensions

Tool	Approach
Vimium	Hints-based link navigation
Vimium C	Extended Vimium
Tridactyl	Full Vim emulation in Firefox

Platform support

macOS is fully supported. Linux and Windows currently expose the shared architecture, ports, and stubs, but still need native implementations for core functionality. On Linux, the platform factory now distinguishes X11, wlroots-based Wayland, GNOME Wayland, KDE Wayland, and unknown sessions so the app can return clearer guidance during startup.

Shared code should prefer platform roles over macOS-specific assumptions:

Use Primary in new cross-platform hotkeys when you mean "Cmd on macOS, Ctrl elsewhere".
Treat Linux as a backend family, not one target: X11 and Wayland may need separate adapters behind the same port.
Keep backend selection in platform/infra code so contributors can extend Linux without editing shared mode logic.
Treat CGO as backend-dependent, not automatically OS-dependent: macOS needs it today, Linux may or may not depending on backend, and Windows should prefer pure-Go Win32 bindings where practical.

Platform	Status
macOS	✅ Stable, all features
Linux	✅ X11 / Wayland (wlroots)
Windows	🔲 Foundations only

Linux-specific setup notes and planned backend targets live in docs/LINUX_SETUP.md.

Interested in porting? Check cross-platform issues or join the Linux discussion.

Contributor quick start for platform work:

just build
just test-foundation
just build-linux      # or: just build-windows

Full compatibility matrix & roadmap

Capability	macOS	Linux	Windows
Recursive Grid	✅	✅	🔲
Grid	✅	✅	🔲
Hints	✅	🔲	🔲
Vim-Style Scrolling	✅	✅	🔲
Direct Mouse Actions	✅	✅	🔲
Global Hotkeys	✅	✅	🔲
Accessibility Integration	✅	🔲	🔲
Native Overlays	✅	✅	🔲

Roadmap

Phase 1 — macOS ✅
- Stable core architecture
- High-performance native bridge
- Full feature set
Phase 2 — Linux
- AT-SPI accessibility integration
- X11/Wayland event capture
- Native overlays
Phase 3 — Windows
- UI Automation (UIA) integration
- Windows Hooks for event capture
- Win32/WinUI overlays

Documentation

Guide	Contents
Installation	Homebrew, Nix, source builds
Configuration	Every TOML option
CLI	IPC commands and scripting
Troubleshooting	Common issues, app-specific fixes
Development	Architecture and build instructions
Architecture	Porting guide and system design
Cross-Platform Guide	Contributor guide for Linux/Windows/platform work
Roadmap	Current priorities and milestones

Contributing

The project is small and the codebase is approachable. PRs welcome.

git checkout -b feature/your-idea
just test && just lint
# open a PR

Keep PRs focused on a single change. See Coding Standards and Development Guide.

Sponsoring

Neru is free and built entirely in my spare time. If it's replaced a paid tool in your workflow, consider sponsoring — it helps justify the hours.

GitHub Sponsors →

Acknowledgments

Built on the shoulders of Homerow, Vimac, Vimium, Mouseless, and Shortcat.

License

MIT — see LICENSE.

Made with ❤️ by y3owk1n

⭐ Star this repo if Neru makes your workflow better

Directories ¶

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

Path	Synopsis
cmd
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/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 the Carbon Event Manager API, enabling system-wide keyboard shortcuts.	Package hotkeys provides comprehensive functionality for registering and handling global hotkeys in the Neru application using the Carbon Event Manager API, 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 provides Linux-specific implementations of infrastructure components.	Package linux provides Linux-specific implementations of infrastructure components.
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/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.