Neru
Master your keyboard, refine your workflow
Navigate macOS without touching your mouse - keyboard-driven productivity at its finest ๐ฑ๏ธโจ๏ธ
Get Started โข Features โข Docs โข Contributing
โจ What is Neru?
Neru (็ทดใ) - a Japanese word meaning "to refine, polish, and master through practice" - is a free, open-source keyboard navigation tool for macOS. Navigate, click, and scroll anywhere on your screen without ever touching your mouse.
Feel free to read the progress and how I use Neru here if you're interested with it.
๐ฏ Why Choose Neru?
- ๐ Always free - No paywalls, no subscriptions, no "upgrade to pro"
- ๐ฌ Universal compatibility - Works with native macOS apps, Electron apps, and all browsers
- โก Lightning fast - Native performance with instant response
- ๐ ๏ธ Power-user friendly - Text-based config for version control and dotfile management
- ๐ค Community-owned - Your contributions shape the project
- ๐ง Scriptable - CLI commands enable automation and integration
๐ Free Alternative To
Neru is a capable free and open-source replacement for:
- Homerow - Modern keyboard navigation (paid)
- Shortcat - Keyboard productivity tool (discontinued)
- Vimac - Vim-style navigation (unmaintained)
- Mouseless - Grid based keyboard navigation (paid)
๐ฏ Core Features
| Feature | Description |
|---|---|
| ๐ฏ Hint & Grid Labels | Click any visible element using keyboard labels |
| โก Direct Actions | Perform mouse actions directly in hints/grid mode (Shift+L, etc.) |
| ๐ Vim Scrolling | Fully configurable scroll keys: j/k, gg/G, custom bindings |
| ๐ Universal Support | Native apps, Electron, Chrome, Firefox, system UI |
| โก Native Performance | Built with Objective-C and Go for instant response |
| ๐ ๏ธ TOML Config | Highly customizable with text-based configuration |
| ๐ซ App Exclusion | Disable Neru in specific applications |
| ๐ฌ CLI Control | IPC commands for scripting and automation |
๐ฎ How It Works
Navigation Modes:
- Hints Mode - Accessibility-based labels on clickable elements
- Grid Mode - Universal coordinate-based navigation (works everywhere!)
- Scroll Mode - Vim-style scrolling at cursor position
- Recursive Grid Mode - Recursive cell selection (u/i/j/k), reset key returns to initial center
Hints Demo โข Grid Demo
๐ Get Started
Install
# Homebrew (recommended)
brew tap y3owk1n/tap
brew install --cask y3owk1n/tap/neru
# Nix Flake
# Add to flake.nix: inputs.neru.url = "github:y3owk1n/neru";
# See docs/INSTALLATION.md for nix-darwin/home-manager setup
# Or build from source
git clone https://github.com/y3owk1n/neru.git
cd neru && just release
Grant Permissions
- Open System Settings
- Navigate to Privacy & Security โ Accessibility
- Enable Neru
Try It
# Start Neru
open -a Neru
# Or install as launchd service for auto-startup
neru services install
# Try default hotkeys:
# Cmd+Shift+Space - Hint mode
# Cmd+Shift+G - Grid mode
# Cmd+Shift+C - Recursive Grid mode
# Cmd+Shift+S - Scroll
When in hint or grid mode, selecting a hint or label will move the cursor to that point. You can also press action keybindings (e.g., Shift+L for left click, Shift+R for right click) to perform actions without switching modes.
See Installation Guide for detailed setup instructions.
๐ Documentation
- Installation Guide - Homebrew, Nix, source builds
- Configuration - Complete TOML reference
- CLI Usage - Command-line interface
- Troubleshooting - Common issues & solutions
- Development - Building & contributing
โ๏ธ Configuration
Neru uses TOML configuration with sensible defaults. Customize everything from hotkeys to visual styling.
[hotkeys]
"Cmd+Shift+Space" = "hints"
"Cmd+Shift+G" = "grid"
[hints]
hint_characters = "asdfghjkl"
background_color = "#FFD700"
See Configuration Guide for all options.
๐๏ธ Design Philosophy
Why TOML config over GUI?
- โก Faster editing than clicking through settings
- ๐ Version control friendly (dotfiles, git)
- ๐ง More powerful than UI constraints
- ๐ ๏ธ Reduces maintenance burden
Why we recommend grid over hints navigation?
- โ Works everywhere (native apps, Electron, browsers, system UI)
- โก Fast and reliable (no accessibility tree traversal)
- ๐ฏ Always accurate (clicks at exact coordinates)
- ๐ง Simple maintenance (no app-specific workarounds)
[!NOTE] We support both hints and grid modes, but we recommend using grid mode as it is mostly usable out of the box without further configuration.
๐ Project Status
Actively maintained with community contributions. PRs welcome!
Contribution ideas:
- Improved app icons & logo
- More navigation mechanism
- More mouse actions
- Website & docs
- More configuration examples for different use cases
โ Compatibility
Neru works with everything:
- Native macOS Apps - Finder, Safari, System Settings, Mail, etc.
- Electron Apps - VS Code, Cursor, Slack, Spotify, Obsidian, Discord
- Browsers - Chrome, Firefox, Safari, Arc, Brave, Zen
- Creative Apps - Adobe Illustrator, Photoshop, Figma
- System UI - Menubar, Dock, Mission Control, Notification Center
See Troubleshooting Guide for app-specific issues.
๐ค Contributing
We welcome contributions! Here's how to get started:
- Fork & Clone the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes following our Coding Standards
- Test thoroughly (
just test && just lint) - Commit conventionally and open a Pull Request
Guidelines:
- Keep PRs focused on a single change
- Add tests for new features
- Update documentation
- Follow existing code style
See Development Guide for build instructions and architecture details.
๐ Acknowledgments
Inspired by these excellent projects:
- Homerow - Modern keyboard navigation
- Vimac - Vim-style navigation
- Shortcat - Keyboard productivity tool
- Vimium - Browser Vim bindings
- Mouseless - Grid navigation
๐ฌ Support
- ๐ Troubleshooting Guide for common issues
- ๐ Open an issue for bugs
- ๐ฌ Discussions for questions
- โญ Star this repo if you find Neru useful!
๐ License
MIT License - see LICENSE for details.
Made with โค๏ธ by y3owk1n
