{"id":34911157,"url":"https://github.com/y3owk1n/neru","last_synced_at":"2026-04-19T05:07:47.418Z","repository":{"id":321773214,"uuid":"1087058511","full_name":"y3owk1n/neru","owner":"y3owk1n","description":"Keyboard-driven navigation for macOS and partial linux (possible for windows) - Navigate and click without touching your mouse.","archived":false,"fork":false,"pushed_at":"2026-04-17T18:33:38.000Z","size":4675,"stargazers_count":248,"open_issues_count":5,"forks_count":14,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-17T19:29:04.632Z","etag":null,"topics":["accessibility","bindings","homerow","homerow-app","keyboard","keyboard-navigation","linux","mac","macos","macos-app","macosx","mouse","mouseless","system-wide","systemwide","vim","vimium","warpd","wayland","x11"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/y3owk1n.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"y3owk1n"}},"created_at":"2025-10-31T10:09:28.000Z","updated_at":"2026-04-17T18:33:32.000Z","dependencies_parsed_at":"2026-02-27T18:07:04.936Z","dependency_job_id":null,"html_url":"https://github.com/y3owk1n/neru","commit_stats":null,"previous_names":["y3owk1n/govim","y3owk1n/neru"],"tags_count":61,"template":false,"template_full_name":null,"purl":"pkg:github/y3owk1n/neru","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y3owk1n%2Fneru","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y3owk1n%2Fneru/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y3owk1n%2Fneru/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y3owk1n%2Fneru/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/y3owk1n","download_url":"https://codeload.github.com/y3owk1n/neru/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y3owk1n%2Fneru/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31995187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","bindings","homerow","homerow-app","keyboard","keyboard-navigation","linux","mac","macos","macos-app","macosx","mouse","mouseless","system-wide","systemwide","vim","vimium","warpd","wayland","x11"],"created_at":"2025-12-26T11:18:19.839Z","updated_at":"2026-04-19T05:07:47.407Z","avatar_url":"https://github.com/y3owk1n.png","language":"Go","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/neru-appicon.png\" alt=\"Neru Logo\" width=\"100\" /\u003e\n\n# 練る · Neru\n\n**Navigate your entire screen without touching the mouse.**\n\n![MacOS Support](https://img.shields.io/badge/MacOS-Stable-blue)\n[![Linux Support](https://img.shields.io/badge/Linux-X11_\u0026_Wayland-blue)](docs/LINUX_SETUP.md)\n![Windows Support](https://img.shields.io/badge/Windows-Foundation-lightgrey)\n\n![Go Version](https://img.shields.io/github/go-mod/go-version/y3owk1n/neru)\n[![Latest Release](https://img.shields.io/github/v/release/y3owk1n/neru)](https://github.com/y3owk1n/neru/releases)\n[![License](https://img.shields.io/github/license/y3owk1n/neru)](LICENSE)\n\n\u003c/div\u003e\n\n---\n\nNeru _(練る — \"to refine through practice\")_ puts your cursor anywhere on screen using only your keyboard. Click, scroll, drag — all without leaving the home row.\n\nIt's a free, open-source alternative to [Homerow](https://www.homerow.app/), [Mouseless](https://mouseless.click/), and [Wooshy](https://wooshy.app). No paywalls, no subscriptions, fully configurable.\n\n\u003e See how the author uses Neru day-to-day → [HOW-I-USE-NERU.md](HOW-I-USE-NERU.md) and a quick demo with `recursive_grid` with my own config:\n\n\u003chttps://github.com/user-attachments/assets/4504dc19-90e6-43c0-9179-28c866513061\u003e\n\n---\n\n## Navigation modes\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"33%\"\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/0d46fa7c-345a-45ee-ad44-7a601c2b7cb1\" alt=\"Recursive Grid Mode\" /\u003e\u003cbr/\u003e\n\u003csub\u003e\u003cb\u003eRecursive Grid\u003c/b\u003e · recommended\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"33%\"\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/d452f972-ce23-4798-955b-6dbfa8435504\" alt=\"Grid Mode\" /\u003e\u003cbr/\u003e\n\u003csub\u003e\u003cb\u003eGrid\u003c/b\u003e\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"33%\"\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/71b13850-1b87-40b5-9ac0-93cff1f2e89b\" alt=\"Hints Mode\" /\u003e\u003cbr/\u003e\n\u003csub\u003e\u003cb\u003eHints\u003c/b\u003e\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n| Mode                  | How it works                                                      | Best for                                       |\n| --------------------- | ----------------------------------------------------------------- | ---------------------------------------------- |\n| **Recursive Grid** ⭐ | Divide screen into cells, narrow recursively with `u`/`i`/`j`/`k` | Everything — works in any app, any window      |\n| **Grid**              | Coordinate grid, jump by row + column label                       | Quick, coarse navigation                       |\n| **Hints**             | Labels appear on every clickable UI element                       | Standard macOS apps with accessibility support |\n| **Scroll**            | Vim-style `j`/`k`, `gg`/`G`, `d`/`u`                              | Scrolling without lifting your hands           |\n\n**Recursive Grid is the recommended daily driver.** It's precise, predictable, and requires no per-app setup — it just works everywhere.\n\n---\n\n## Features\n\n- **All mouse actions** — left, right, and middle click; drag \u0026 drop; all key-bound\n- **Sticky modifiers** — tap `Shift` or `Cmd` once to apply to your next click, no holding\n- **Per-app exclusions** — opt specific apps out by bundle ID\n- **CLI \u0026 scripting** — full IPC-based CLI for shell scripts and hotkey managers\n- **TOML config** — every keybinding, color, and behavior in one file you can version-control\n\nWorks 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.\n\n---\n\n## Installation\n\n**macOS (Homebrew — recommended):**\n\n\u003e [!NOTE]\n\u003e The homebrew tap is maintained in another repo: [y3owk1n/homebrew-tap](https://github.com/y3owk1n/homebrew-tap)\n\u003e If there's a problem with the tap, please open an issue in that repo or even better, a PR.\n\n```bash\nbrew tap y3owk1n/tap\nbrew install --cask y3owk1n/tap/neru\n```\n\n**macOS / Linux (Nix Flake):**\n\n```bash\n# inputs.neru.url = \"github:y3owk1n/neru\";\n# Modules: nix-darwin (macOS) · nixosModules (Linux) · home-manager (both)\n# See docs/INSTALLATION.md for full setup\n```\n\n**From source (any platform):**\n\n```bash\ngit clone https://github.com/y3owk1n/neru.git\ncd neru \u0026\u0026 just release\n```\n\n**Post-install (macOS):** grant accessibility access — **System Settings → Privacy \u0026 Security → Accessibility → enable Neru**.\n\n```bash\nopen -a Neru              # launch\nneru services install     # auto-start on login (use this only if you're not using nix with launchagents enabled)\n```\n\n**Post-install (Linux):** see [Linux Setup →](docs/LINUX_SETUP.md) for display-server requirements and permissions.\n\n```bash\nneru launch               # launch\n```\n\nFull walkthrough: [Installation Guide →](docs/INSTALLATION.md)\n\n---\n\n## Default hotkeys\n\n| Hotkey            | Action            |\n| ----------------- | ----------------- |\n| `Cmd+Shift+C`     | Recursive Grid ⭐ |\n| `Cmd+Shift+G`     | Grid              |\n| `Cmd+Shift+Space` | Hints             |\n| `Cmd+Shift+S`     | Scroll            |\n| `Shift+L`         | Left click        |\n| `Shift+R`         | Right click       |\n\nAll hotkeys are remappable. See [Configuration Reference →](docs/CONFIGURATION.md#hotkeys)\n\n\u003e **Note:** Adding any custom hotkey replaces all defaults. Re-declare every hotkey you want to keep.\n\n---\n\n## Configuration\n\nEverything lives in `~/.config/neru/config.toml` — one file, plain text, dotfile-friendly.\n\n```bash\nneru config init      # generate a commented starter config\nneru config validate  # check for errors\nneru config reload    # hot-reload into a running daemon\n```\n\nVersion-control it, share it, script against it. No settings GUI, no hidden state.\n\nFull reference: [Configuration Docs →](docs/CONFIGURATION.md) · Community configs: [Config Showcases →](/docs/CONFIG_SHOWCASES.md)\n\n---\n\n## How Neru compares\n\n### macOS\n\n| Tool                                         | Approach                               | Price    | Open Source        |\n| -------------------------------------------- | -------------------------------------- | -------- | ------------------ |\n| **Neru**                                     | Hints + Grid + Recursive Grid + Scroll | **Free** | ✅                 |\n| [Homerow](https://www.homerow.app/)          | Hints (fuzzy search + labels)          | Paid     | ❌                 |\n| [Wooshy](https://wooshy.app)                 | Hints (search-to-click)                | Paid     | ❌                 |\n| [Mouseless](https://mouseless.click/)        | Grid-based pointer control             | Paid     | ❌                 |\n| [Scoot](https://github.com/mjrusso/scoot)    | Hints + Grid + Freestyle               | Free     | ✅                 |\n| [Vimac](https://github.com/dexterleng/vimac) | Hints + Grid                           | Free     | ✅ ⚠️ unmaintained |\n| [warpd](https://github.com/rvaiya/warpd)     | Hints + Grid + Normal                  | Free     | ✅ ⚠️ low activity |\n| [Shortcat](https://shortcat.app/)            | Hints (fuzzy search)                   | Free     | ❌ discontinued    |\n\n### Browser extensions\n\n| Tool                                                | Approach                      |\n| --------------------------------------------------- | ----------------------------- |\n| [Vimium](https://github.com/philc/vimium)           | Hints-based link navigation   |\n| [Vimium C](https://github.com/gdh1995/vimium-c)     | Extended Vimium               |\n| [Tridactyl](https://github.com/tridactyl/tridactyl) | Full Vim emulation in Firefox |\n\n---\n\n## Platform support\n\nmacOS is fully supported. Linux and Windows currently expose the shared\narchitecture, ports, and stubs, but still need native implementations for core\nfunctionality. On Linux, the platform factory now distinguishes X11,\nwlroots-based Wayland, GNOME Wayland, KDE Wayland, and unknown sessions so the\napp can return clearer guidance during startup.\n\nShared code should prefer platform roles over macOS-specific assumptions:\n\n- Use `Primary` in new cross-platform hotkeys when you mean \"Cmd on macOS, Ctrl elsewhere\".\n- Treat Linux as a backend family, not one target: X11 and Wayland may need separate adapters behind the same port.\n- Keep backend selection in platform/infra code so contributors can extend Linux without editing shared mode logic.\n- Treat CGO as backend-dependent, not automatically OS-dependent: macOS needs it today, Linux may or may not depending on backend, and Windows should prefer pure-Go Win32 bindings where practical.\n\n| Platform    | Status                     |\n| ----------- | -------------------------- |\n| **macOS**   | ✅ Stable, all features    |\n| **Linux**   | ✅ X11 / Wayland (wlroots) |\n| **Windows** | 🔲 Foundations only        |\n\nLinux-specific setup notes and planned backend targets live in\n[docs/LINUX_SETUP.md](docs/LINUX_SETUP.md).\n\n**Interested in porting?** Check [`cross-platform` issues](https://github.com/y3owk1n/neru/issues?q=is%3Aopen+is%3Aissue+label%3Across-platform) or join the [Linux discussion](https://github.com/y3owk1n/neru/discussions/559).\n\nContributor quick start for platform work:\n\n```bash\njust build\njust test-foundation\njust build-linux      # or: just build-windows\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eFull compatibility matrix \u0026 roadmap\u003c/summary\u003e\n\n| Capability                | macOS | Linux | Windows |\n| :------------------------ | :---: | :---: | :-----: |\n| Recursive Grid            |  ✅   |  ✅   |   🔲    |\n| Grid                      |  ✅   |  ✅   |   🔲    |\n| Hints                     |  ✅   |  🔲   |   🔲    |\n| Vim-Style Scrolling       |  ✅   |  ✅   |   🔲    |\n| Direct Mouse Actions      |  ✅   |  ✅   |   🔲    |\n| Global Hotkeys            |  ✅   |  ✅   |   🔲    |\n| Accessibility Integration |  ✅   |  🔲   |   🔲    |\n| Native Overlays           |  ✅   |  ✅   |   🔲    |\n\n**Roadmap**\n\n- **Phase 1 — macOS** ✅\n  - [x] Stable core architecture\n  - [x] High-performance native bridge\n  - [x] Full feature set\n- **Phase 2 — Linux**\n  - [ ] AT-SPI accessibility integration\n  - [x] X11/Wayland event capture\n  - [x] Native overlays\n- **Phase 3 — Windows**\n  - [ ] UI Automation (UIA) integration\n  - [ ] Windows Hooks for event capture\n  - [ ] Win32/WinUI overlays\n\n\u003c/details\u003e\n\n---\n\n## Documentation\n\n| Guide                                          | Contents                                          |\n| ---------------------------------------------- | ------------------------------------------------- |\n| [Installation](docs/INSTALLATION.md)           | Homebrew, Nix, source builds                      |\n| [Configuration](docs/CONFIGURATION.md)         | Every TOML option                                 |\n| [CLI](docs/CLI.md)                             | IPC commands and scripting                        |\n| [Troubleshooting](docs/TROUBLESHOOTING.md)     | Common issues, app-specific fixes                 |\n| [Development](docs/DEVELOPMENT.md)             | Architecture and build instructions               |\n| [Architecture](docs/ARCHITECTURE.md)           | Porting guide and system design                   |\n| [Cross-Platform Guide](docs/CROSS_PLATFORM.md) | Contributor guide for Linux/Windows/platform work |\n| [Roadmap](docs/ROADMAP.md)                     | Current priorities and milestones                 |\n\n---\n\n## Contributing\n\nThe project is small and the codebase is approachable. PRs welcome.\n\n```bash\ngit checkout -b feature/your-idea\njust test \u0026\u0026 just lint\n# open a PR\n```\n\nKeep PRs focused on a single change. See [Coding Standards](docs/CODING_STANDARDS.md) and [Development Guide](docs/DEVELOPMENT.md).\n\n---\n\n## Sponsoring\n\nNeru 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.\n\n[**GitHub Sponsors →**](https://github.com/sponsors/y3owk1n)\n\n---\n\n## Acknowledgments\n\nBuilt on the shoulders of [Homerow](https://www.homerow.app/), [Vimac](https://github.com/dexterleng/vimac), [Vimium](https://github.com/philc/vimium), [Mouseless](https://mouseless.click/), and [Shortcat](https://shortcat.app/).\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ by [y3owk1n](https://github.com/y3owk1n)**\n\n⭐ Star this repo if Neru makes your workflow better\n\n\u003c/div\u003e\n","funding_links":["https://github.com/sponsors/y3owk1n"],"categories":["🛠️ Productivity"],"sub_categories":["☸️ Kubernetes"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fy3owk1n%2Fneru","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fy3owk1n%2Fneru","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fy3owk1n%2Fneru/lists"}