neru

README

練る · Neru

Navigate your entire screen without touching the mouse.

---

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

---

Navigation modes

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

[!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.

# Homebrew (recommended — gets you auto-updates)
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

Then grant accessibility access: System Settings → Privacy & Security → Accessibility → enable Neru.

open -a Neru              # launch
neru services install     # auto-start on login

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 →

Note: Adding any custom hotkey replaces all defaults. Re-declare every hotkey you want to keep.

---

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

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 foundations are in place — they need contributors to implement the native layer.

Platform	Status
macOS	✅ Stable, all features
Linux	🔲 Needs contributor
Windows	🔲 Needs contributor

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

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

---

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