Neru

Master your keyboard, refine your workflow

Navigate macOS without touching your mouse - keyboard-driven productivity at its finest 🖱️⌨️

Installation • Quick Start • 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.

🎯 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)

---

🚀 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

1. Open System Settings
2. Navigate to Privacy & Security → Accessibility
3. 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+S     - Scroll

When in hint or grid mode, selecting a hint or label will move the cursor to that point. You can also press Tab when in those modes to enter action mode, and use keybindings to perform actions on the current cursor position, e.g., l for left click, r for right click, d for double-click, m for middle-click, etc.

See Installation Guide for detailed setup instructions.

---

🎯 Core Features

Feature	Description
🎯 Hint Labels	Click any visible element using keyboard labels
🎬 Action Mode	Choose click type: left, right, double, middle, drag & drop
📜 Vim Scrolling	Scroll anywhere with j/k, gg/G, Ctrl+D/U
🌐 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

Four Navigation Modes:

1. Hints Mode - Accessibility-based labels on clickable elements
2. Grid Mode - Universal coordinate-based navigation (works everywhere!)
3. Scroll Mode - Vim-style scrolling at cursor position
4. Action Mode - Interactive mouse actions at cursor position

Hints Demo • Grid Demo

📚 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.

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork & Clone the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following our Coding Standards
4. Test thoroughly (just test && just lint)
5. 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.

🏗️ 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 grid-based 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)

📊 Project Status

Actively maintained with community contributions. PRs welcome!

Future Ideas:

• Service management commands
• Improved app icons

Known Issues:

• Hold/unhold actions don't work in Finder (help appreciated!)

✅ 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.

---

📄 License

MIT License - see LICENSE for 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!

Made with ❤️ by y3owk1n