neru

module

v1.21.1 Latest Latest Go to latest Published: Feb 23, 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

Mouse-free macOS navigation. Free, open-source, endlessly customisable.

Go Version

Get Started · Features · Configuration · Docs · Contributing

_{Recursive Grid · recommended}

_Grid

_Hints

What is Neru?

Neru (練る) — Japanese for "to refine and master through practice" — lets you navigate, click, and scroll anywhere on macOS using only your keyboard. No mouse. No trackpad. No limits.

It's the free, open-source alternative to Homerow, Mouseless, and Wooshy — with zero paywalls, zero subscriptions, and everything configurable down to the last pixel.

Want to see how the author actually uses Neru day-to-day? Read the full story →

✨ Features

Recursive Grid Mode (recommended) — divide your screen into a coordinate grid and drill into any region with u/i/j/k until you land exactly where you want. Works in every app, every window, every corner of macOS — no exceptions, no app-specific setup.

Grid Mode — same coordinate-based approach without the recursive subdivision, great for quick coarse navigation.

Hints Mode — labels appear on every clickable element for instant accessibility-driven navigation. Requires accessibility tree support, so some apps may need additional configuration.

Recursive Grid is recommended as your daily driver: it's precise, predictable, works everywhere out-of-the-box, and never needs app-specific tweaks.

🖱️ Direct Mouse Actions

In any navigation mode, trigger mouse actions without switching modes — left click, right click, double click, middle click, and drag & drop via direct action keybindings.

📜 Vim-Style Scrolling

Scroll anywhere with familiar j/k, gg/G, and Ctrl+D/Ctrl+U bindings — all fully remappable.

🚫 Per-App Exclusions

Disable Neru in specific apps where you don't need it.

💬 CLI & Scripting

Full IPC-based CLI lets you control Neru programmatically, integrate with other tools, or build your own automation workflows.

⚙️ Configuration

Neru is configured entirely through a single TOML file — no GUI required. Every keybinding, every color, every behavior is yours to define.

Why TOML over a settings UI?

Version-control your config in your dotfiles
Edit faster than clicking through preference panels
No UI = less code to maintain = more stability
Shareable, reproducible, scriptable

See the full Configuration Reference →

🚀 Get Started

1. Install

# Homebrew (recommended)
brew tap y3owk1n/tap
brew install --cask y3owk1n/tap/neru

# Nix Flake
# inputs.neru.url = "github:y3owk1n/neru";
# See docs/INSTALLATION.md for nix-darwin / home-manager setup

# Build from source
git clone https://github.com/y3owk1n/neru.git
cd neru && just release

2. Grant Accessibility Permission

Open System Settings → Privacy & Security → Accessibility
Enable Neru

3. Launch & Try

# Start Neru
open -a Neru

# Auto-start on login
neru services install

Default Hotkey	Action
`Cmd+Shift+C`	Recursive grid mode (recommended)
`Cmd+Shift+G`	Grid mode
`Cmd+Shift+Space`	Hints mode
`Cmd+Shift+S`	Scroll mode
`Shift+L`	Left click (in any mode)
`Shift+R`	Right click (in any mode)

These are just subset of available keys. All hotkeys and actions are fully remappable.

Full setup walkthrough: Installation Guide →

✅ Works Everywhere

Category	Apps
Native macOS	Finder, Safari, Mail, System Settings, Terminal
Electron	VS Code, Cursor, Slack, Spotify, Obsidian, Discord
Browsers	Chrome, Firefox, Safari, Arc, Brave, Zen
Creative	Figma, Adobe Illustrator, Photoshop
System UI	Menubar, Dock, Mission Control, Notification Center

Grid mode works universally. Hints mode works where the accessibility tree is exposed — see the Troubleshooting Guide for app-specific notes.

🆚 Free Alternative To

Tool	Status	Neru
Homerow	Paid	✅ Free
Mouseless	Paid	✅ Free
Wooshy	Paid	✅ Free
Shortcat	Discontinued	✅ Active
Vimac	Unmaintained	✅ Maintained

📚 Documentation

Installation Guide — Homebrew, Nix, source builds
Configuration Reference — every TOML option
CLI Usage — IPC commands and scripting
Troubleshooting — common issues and app-specific fixes
Development — architecture and build instructions

🤝 Contributing

Contributions are welcome. The project is small and the codebase is approachable.

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

Follow the Coding Standards and keep PRs focused on a single change. See Development Guide for architecture details.

Good first contributions:

App icon / logo improvements
New navigation mechanisms
Additional mouse action types
Config examples for common setups
Demo videos
Performance improvements
Bug fixes

🙏 Acknowledgments

Built on the shoulders of: Homerow · Vimac · Vimium · Mouseless · Shortcat

📄 License

MIT — see LICENSE for details.

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.
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 the mode indicator overlay component.	Package modeindicator provides the mode indicator overlay component.
app/components/overlayutil Package overlayutil provides shared utilities for overlay management.	Package overlayutil provides shared utilities for overlay management.
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/systray Package systray provides system tray functionality for the Neru application.	Package systray provides system tray functionality for the Neru application.
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.
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 provides an adapter for the macOS accessibility API.	Package accessibility provides an adapter for the macOS accessibility API.
core/infra/appmetrics Package appmetrics provides metrics collection and reporting.	Package appmetrics provides metrics collection and reporting.
core/infra/apptrace Package apptrace provides tracing utilities.	Package apptrace provides tracing utilities.
core/infra/appwatcher Package appwatcher provides comprehensive functionality for monitoring application lifecycle events on macOS, enabling Neru to respond to application launches, terminations, activations, and deactivations.	Package appwatcher provides comprehensive functionality for monitoring application lifecycle events on macOS, enabling Neru to respond to application launches, terminations, activations, and deactivations.
core/infra/bridge Package bridge provides comprehensive Go bindings for Objective-C APIs used in the Neru application, enabling seamless integration with macOS system frameworks for accessibility, hotkeys, and overlay functionality.	Package bridge provides comprehensive Go bindings for Objective-C APIs used in the Neru application, enabling seamless integration with macOS system frameworks for accessibility, hotkeys, and overlay functionality.
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-based applications, enabling proper UI element detection in applications that don't properly expose their interface to the macOS accessibility API by default.	Package electron provides enhanced accessibility support for Electron-based applications, enabling proper UI element detection in applications that don't properly expose their interface to the macOS accessibility API 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/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/systray Package systray provides a cross-platform system tray menu implementation.	Package systray provides a cross-platform system tray menu implementation.
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.