neru

module

v1.43.0 Latest Latest Go to latest Published: Jun 6, 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.

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

It is a free, blazing-fast, and open-source alternative to paid/subscription utilities like Homerow, Mouseless, and Wooshy. It is fully configurable, lightweight, and respects your privacy.

[!TIP] See how the author uses Neru day-to-day → HOW-I-USE-NERU.md and watch the recursive_grid demo:

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

Neru offers four distinct modes tailored for every navigation requirement.

_{Recursive Grid · recommended}

_Grid

_{Hints (Dual-Engine)
AX-Tree & Vision OCR}

Mode	Core Mechanism	Best For
Recursive Grid ⭐	Divides screen into cells; narrow recursively using home-row keys (`u`/`i`/`j`/`k`).	Everything — works flawlessly in any app, web browser, canvas, or game.
Hints (Dual-Engine)	Places labels on clickable elements using either OS Accessibility APIs or Native Vision OCR.	Standard macOS apps, Electron apps, and complex design tools (e.g. Figma).
Grid	Standard coordinate grid; jump directly by row + column label.	Rapid, coarse pointer adjustments across large monitors.
Scroll	Vim-style keyboard scrolling (`j`/`k` to scroll, `u`/`d` for half pages).	Reading docs, articles, and code without lifting your hands.

🚀 Features

Full Pointer Control — Bind left, right, middle clicks, double clicks, and drag & drop to home-row keys.
Sticky Modifiers — Tap Shift or Cmd once to apply them to your next mouse click without holding.
Universal Application Support — Works in native AppKit/SwiftUI, Electron (VS Code, Slack, Obsidian), Web Browsers (Safari, Chrome, Firefox), Creative Suites (Figma), and system components (Dock, Menu Bar, Mission Control).
CLI & Automation — Rich IPC-based command line interface for custom shell scripting, hammerspoon integration, and keyboard managers (e.g. Raycast, Alfred).
TOML Configuration — Easily version-control your entire setup (keybindings, theme, overlays) in a single plain text file.

📥 Installation

macOS (Homebrew — Recommended)

[!NOTE] The Homebrew tap is maintained at y3owk1n/homebrew-tap.

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

macOS / Linux (Nix Flake)

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

Building From Source

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

Post-Installation Setup

macOS Accessibility: Grant access in System Settings → Privacy & Security → Accessibility → enable Neru.
Daemon Management:

open -a Neru              # Launch the app (one off launching)
neru services install     # Auto-start on login (highly recommended) and restart on exit

For display-server requirements on Linux, see the Linux Setup Guide.

⌨️ Default Hotkeys

All hotkeys are remappable to suit your custom keyboard layouts (Colemak, Dvorak, etc.).

Hotkey	Action
`Cmd+Shift+C`	Activate Recursive Grid ⭐
`Cmd+Shift+Space`	Activate Hints
`Cmd+Shift+G`	Activate Grid
`Cmd+Shift+S`	Activate Scroll
`Shift+L` (in mode)	Execute Left Click
`Shift+R` (in mode)	Execute Right Click

If you come from vimium or homerow or anything similar and expecting fill label with auto click (neru supports it, but need some configuration, see tips and tricks). Out of the box, you'll need to use keybinding for mouse action like Shift+L for left click. Why not auto clicking it? The rationale behind this decision is because of multiple modes that we supports plus supporting on different mouse actions other than only clicking.

Read the Configuration Reference to customize bindings.

⚙️ Configuration

Your configuration lives at ~/.config/neru/config.toml. It's human-readable, dotfile-friendly, and changes are applied instantly without restarting.

neru config init      # Generate a fully-commented starter configuration
neru config validate  # Validate your TOML file structure and types
neru config reload    # Hot-reload configurations into the running daemon

For all settings, see the Configuration Guide and explore user showcases in Config Showcases.

⚖️ How Neru Compares

macOS Ecosystem

Neru is unique in offering both coordinate-based grids and a dual-engine (AX + Vision OCR) hints mode in a single free, open-source tool.

Tool	Engine Approach	Price	Open Source	Active / Maintained
Neru 練る	Grid + Recursive Grid + AX-Tree Hints + Vision OCR Hints	Free	✅	✅ Active
Homerow	AX-Tree Hints (with fuzzy search)	Paid	❌	✅ Active
Wooshy	AX-Tree Search-to-click	Paid	❌	✅ Active
Mouseless	Grid pointer control	Paid	❌	✅ Active
Scoot	AX Hints + Grid	Free	✅	🔲 Low Activity
Vimac	AX Hints	Free	✅	❌ Unmaintained
warpd	Grid + Hints + Normal Pointer	Free	✅	🔲 Low Activity
Shortcat	Hints (fuzzy search)	Free	❌	❌ discontinued
Glyphlow	Hints + vim text editing	Free	✅	✅ Active

Browser Extensions

If you use keyboard navigators on the web, Neru brings that exact comfort to your entire operating system:

Vimium — Standard hints-based web navigation.
Vimium C — Extended fast Vimium branch.
Tridactyl — Complete Vim environment inside Firefox.

💻 Platform Support & Capabilities

macOS is fully featured and stable. Support for Linux (X11 & Wayland) is actively developing.

Capability	macOS	Linux	Windows
Recursive Grid	✅	✅	🔲
Grid	✅	✅	🔲
Vim-Style Scroll	✅	✅	🔲
Direct Mouse Injection	✅	✅	🔲
Global Hotkeys	✅	✅	🔲
Accessibility Hints (AX)	✅	🔲	🔲
Vision-Powered Hints (OCR)	✅	🔲	🔲
Native High-Perf Overlays	✅	✅	🔲

Detailed backend documentation and roadmap plans live in docs/ROADMAP.md and docs/CROSS_PLATFORM.md.

🤝 Contributing

Neru has a modular, clean hexagonal architecture (Ports & Adapters) written in Go and Objective-C, making it exceptionally easy to add features or platform adapters.

git checkout -b feature/amazing-feature
just test && just lint
# Open a pull request!

Refer to Development Guide and Coding Standards for more details.

💖 Sponsoring

Neru is built and maintained entirely in spare time. If Neru has streamlined your day-to-day workflow, improved your ergonomics, or saved you money, please consider sponsoring:

👉 GitHub Sponsors

🎓 Acknowledgments

We stand on the shoulders of giants. Our deepest gratitude goes to the creators of Homerow, Vimac, Vimium, Mouseless, and Shortcat.

📄 License

Distributed under the MIT License. See LICENSE for more details.

Made with ❤️ by y3owk1n

⭐ Star this repository if Neru makes your workflow better!

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/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 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/space Package space provides functions for focusing Mission Control spaces.	Package space provides functions for focusing Mission Control spaces.
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.