y3owk1n/neru / .agents/skills/neru-ask
neru-ask
VerifiedAnswer a Neru user's question about what Neru does, which command, flag, or config key does a thing, why something does not work, or what to try next, from the help, man pages, and docs of their installed version rather than from memory. Routes config work to neru-setup-config. Use when a Neru user asks what Neru can do, how to do something with it, which command to run, why hints or a hotkey do nothing, or which skill to use.
Answering questions about Neru
Neru is a keyboard-driven mouse replacement. A daemon watches global hotkeys and draws overlays, and a CLI sends it commands over a socket. Modes take the keyboard until a target is picked. Hints label clickable elements, grid and recursive grid divide the screen, scroll moves content, monitor select jumps between displays. Actions click, scroll, and move the cursor without a mode. Every answer should come from the installed version, since commands, flags, and keys change between releases.
What every install has
Check these before anything remote. The install script, Homebrew, Nix, and a source build all ship them.
neru agent-guideandneru describe, on a build that has them. The guide names the installed build's version and docs.neru describe --jsonlists every mode, mode flag, action, config key and event the build reads, withheresaying whether each works on this machine. An older build answersunknown command, so fall back to the help below.neru --help, thenneru <command> --help. The help lists the flags and accepted values of the installed version.man neruon macOS and Linux, and one page per subcommand such asman neru-hints,man neru-config-set, andman neru-action-left_click.apropos nerulists them. Windows has noman, and--helpcarries the same text.neru statusfor whether the daemon runs and which mode is open.neru doctorfor config validity, socket health, permissions, and which capabilities this platform has. It runs without the daemon.neru query hintsfor every element hints would label in the focused window, with its role and text, without drawing anything. Run it first for any "hints show nothing in app X" report. From a terminal it reports the terminal, so run it from a hotkey or assleep 3; neru query hints. Versions before it haveneru hints --debug, which prints a sample.neru config dumpfor the config in force, defaults filled in.neru roles --explainfor the clickable roles and how each resolves here.neru docs cliandneru docs configopen the two references in a browser at the installed version.
For anything the help does not cover, fetch the doc at the installed version:
tag=$(neru --version | sed -n '1s/^Neru version //p' | cut -d- -f1)
case $tag in v*.*.*) ;; *) tag=main ;; esac
base="https://raw.githubusercontent.com/y3owk1n/neru/$tag/docs"
curl -fsSL "$base/reference/cli.md" || curl -fsSL "$base/CLI.md"
A release build prints its tag. A dev build prints v1.2.3-14-gabcdef,
which the cut maps to the release it was built from. On Windows, where
sed and cut are usually absent, the same fetch in PowerShell:
$tag = (((neru --version)[0] -replace '^Neru version ', '') -split '-')[0]
if ($tag -notmatch '^v\d+\.\d+\.\d+$') { $tag = 'main' }
$base = "https://raw.githubusercontent.com/y3owk1n/neru/$tag/docs"
try { Invoke-RestMethod "$base/reference/cli.md" } catch { Invoke-RestMethod "$base/CLI.md" }
Each doc, with the name it had in releases before the docs moved. When the
new path returns 404, the installed release predates the move, so fetch the
old name from the same docs/ URL:
| Doc | Before the move | What it covers |
|---|---|---|
reference/cli.md | CLI.md | every command and flag |
guide/scripting.md | CLI.md | driving Neru from scripts and other hotkey tools |
reference/ipc.md | CLI.md | the IPC protocol |
reference/configuration.md | CONFIGURATION.md | every key with its default and platform column |
concepts/bindings.md | CONFIGURATION.md | what a binding can run, and which binding answers a key |
concepts/glossary.md | not in older releases, skip it | the words the docs use |
guide/getting-started.md | CONFIGURATION.md | first launch, permissions, first hotkey |
guide/using-neru.md | CONFIGURATION.md | how each mode is used, clicks, drag, sticky modifiers |
guide/configuring.md | CONFIGURATION.md | config file location, layering, reloading, config set |
guide/recipes.md | TIPS_TRICKS.md | worked recipes such as Vimium-style click on select, drag with any button, cycling modes on one key, and driving Neru from skhd |
guide/troubleshooting.md | TROUBLESHOOTING.md | when something does not work |
guide/installation.md | INSTALLATION.md | install methods and login services |
reference/platform-support.md | CROSS_PLATFORM.md | what each platform supports |
guide/linux.md, guide/linux-desktops.md | LINUX_SETUP.md, LINUX_DESKTOPS.md | Linux permissions and per-compositor notes |
What Neru does
| Ask | Answer with |
|---|---|
| Click something on screen by keyboard | neru hints --action left_click, or right_click, middle_click |
| Click where hints find nothing | neru grid, neru recursive_grid or neru bisect, or neru hints --strategy vision |
| Filter hints by typing | neru hints --search, or / inside hints |
| Scroll without a mouse | neru scroll, or neru action scroll_down --steps N |
| Move the cursor to a spot, display, or grid cell | neru action move_mouse, move_monitor, move_cell |
| Nudge the cursor and keep it moving while held | neru action move_mouse_relative, glide under [held_repeat] |
| Drag | left_click --state down, move, left_click --state up |
| Jump between monitors | neru monitor_select |
| Type text or press keys | neru action feed |
| Click without moving the real cursor | save_cursor_pos, then the click, then restore_cursor_pos |
| Chain steps as one unit | neru run "..." "...", or [macros] in config, see neru-setup-config |
| Bind a key to any of the above | [hotkeys] in config, see neru-setup-config |
| Change hint letters, colours, grid size | neru config set <key> <value>, see neru-setup-config |
| Make one app behave differently | [[hints.app_configs]] by bundle id, see neru-setup-config |
| Hide overlays while screen sharing | neru toggle-screen-share |
| Run Neru at login | neru services install, see neru-setup-config |
| Pause Neru without quitting | neru stop, then neru start |
Things a user often does not know:
- Hints have four strategies.
axtreereads the accessibility tree and is the default.visionrecognises text on a screen capture, and on macOS rectangles too.contourfinds edges on every platform, andsegmentfinds controls and words from pixels on every platform. An app with a poor tree, such as an Electron app or a game, gets--strategy visionfor one call or a per-app strategy in config. - Grid modes need no accessibility tree. When hints show nothing in an app, grid and recursive grid still work, because they divide the screen rather than read elements.
- Hints only label roles in
hints.clickable_roles. A missing hint is usually a role outside that list.neru query hintsshows what was collected,neru roles --explainshows what the platform can name, andneru hints --roleoverrides the list for one call. - Inside a mode the keys are bindable too. Each mode has its own
[<mode>.hotkeys]table, so Shift+L for a left click inside hints, Tab to cycle, and the arrow keys to nudge are defaults, not fixed. - Linux ships no default global hotkeys. The modes exist but nothing is
bound until
[hotkeys]or the compositor binds them. That is by design. - One config works on every platform. A key, flag, or action the current
platform cannot act on loads with a warning, listed under
platform_supportinneru doctor. It is not an error. - Runtime toggles do not persist.
toggle-scroll-invert,toggle-cursor-follow-selection, andtoggle-screen-sharelast until the daemon restarts. The lasting form is the config key. - The CLI needs the daemon for most things. Modes, actions,
config set,config dump, andstatusall talk to it.config init,config validate,doctor, androlesrun without it. - There is no log file by default.
logging.disable_file_loggingistrueout of the box. Before telling a user to read the log, have them set it tofalseand restart, then read~/Library/Logs/neru/app.logon macOS,~/.local/state/neru/log/app.logon Linux, or%LOCALAPPDATA%\neru\log\app.logon Windows.
Routing
- Config, hotkeys, macros, modes, per-app overrides, or service work goes to
neru-setup-config. - Building a tool on Neru, such as a status bar, a launcher, or a program
that reads its state or drives it, goes to
neru-build-integration. - A question with a one-command answer gets the command and the help page that documents it.
- When something does not work, in this order:
neru status,neru doctor, thenneru query hintsfor a hints report orneru config validatefor a hotkey report, then the Troubleshooting doc as above, before guessing at a cause. Its Permissions and Hotkeys Not Working sections cover most reports. On macOS, a hotkey that never fires after an update is usually a stale Accessibility grant. Remove Neru from the list and add it again. - A bug or a missing feature goes to a GitHub issue on
y3owk1n/neru. Blank issues are disabled, so use the issue forms, and includeneru --versionandneru doctoroutput. Questions and config help belong in Discussions.
Do not answer flags or key names from memory. Run --help or read the man
page first.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |