Skip to content

y3owk1n/neru / .agents/skills/neru-ask

neru-ask

Verified

Answer 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-guide and neru describe, on a build that has them. The guide names the installed build's version and docs. neru describe --json lists every mode, mode flag, action, config key and event the build reads, with here saying whether each works on this machine. An older build answers unknown command, so fall back to the help below.
  • neru --help, then neru <command> --help. The help lists the flags and accepted values of the installed version.
  • man neru on macOS and Linux, and one page per subcommand such as man neru-hints, man neru-config-set, and man neru-action-left_click. apropos neru lists them. Windows has no man, and --help carries the same text.
  • neru status for whether the daemon runs and which mode is open.
  • neru doctor for config validity, socket health, permissions, and which capabilities this platform has. It runs without the daemon.
  • neru query hints for 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 as sleep 3; neru query hints. Versions before it have neru hints --debug, which prints a sample.
  • neru config dump for the config in force, defaults filled in.
  • neru roles --explain for the clickable roles and how each resolves here.
  • neru docs cli and neru docs config open 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:

DocBefore the moveWhat it covers
reference/cli.mdCLI.mdevery command and flag
guide/scripting.mdCLI.mddriving Neru from scripts and other hotkey tools
reference/ipc.mdCLI.mdthe IPC protocol
reference/configuration.mdCONFIGURATION.mdevery key with its default and platform column
concepts/bindings.mdCONFIGURATION.mdwhat a binding can run, and which binding answers a key
concepts/glossary.mdnot in older releases, skip itthe words the docs use
guide/getting-started.mdCONFIGURATION.mdfirst launch, permissions, first hotkey
guide/using-neru.mdCONFIGURATION.mdhow each mode is used, clicks, drag, sticky modifiers
guide/configuring.mdCONFIGURATION.mdconfig file location, layering, reloading, config set
guide/recipes.mdTIPS_TRICKS.mdworked recipes such as Vimium-style click on select, drag with any button, cycling modes on one key, and driving Neru from skhd
guide/troubleshooting.mdTROUBLESHOOTING.mdwhen something does not work
guide/installation.mdINSTALLATION.mdinstall methods and login services
reference/platform-support.mdCROSS_PLATFORM.mdwhat each platform supports
guide/linux.md, guide/linux-desktops.mdLINUX_SETUP.md, LINUX_DESKTOPS.mdLinux permissions and per-compositor notes

What Neru does

AskAnswer with
Click something on screen by keyboardneru hints --action left_click, or right_click, middle_click
Click where hints find nothingneru grid, neru recursive_grid or neru bisect, or neru hints --strategy vision
Filter hints by typingneru hints --search, or / inside hints
Scroll without a mouseneru scroll, or neru action scroll_down --steps N
Move the cursor to a spot, display, or grid cellneru action move_mouse, move_monitor, move_cell
Nudge the cursor and keep it moving while heldneru action move_mouse_relative, glide under [held_repeat]
Dragleft_click --state down, move, left_click --state up
Jump between monitorsneru monitor_select
Type text or press keysneru action feed
Click without moving the real cursorsave_cursor_pos, then the click, then restore_cursor_pos
Chain steps as one unitneru 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 sizeneru 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 sharingneru toggle-screen-share
Run Neru at loginneru services install, see neru-setup-config
Pause Neru without quittingneru stop, then neru start

Things a user often does not know:

  • Hints have four strategies. axtree reads the accessibility tree and is the default. vision recognises text on a screen capture, and on macOS rectangles too. contour finds edges on every platform, and segment finds controls and words from pixels on every platform. An app with a poor tree, such as an Electron app or a game, gets --strategy vision for 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 hints shows what was collected, neru roles --explain shows what the platform can name, and neru hints --role overrides 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_support in neru doctor. It is not an error.
  • Runtime toggles do not persist. toggle-scroll-invert, toggle-cursor-follow-selection, and toggle-screen-share last 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, and status all talk to it. config init, config validate, doctor, and roles run without it.
  • There is no log file by default. logging.disable_file_logging is true out of the box. Before telling a user to read the log, have them set it to false and restart, then read ~/Library/Logs/neru/app.log on macOS, ~/.local/state/neru/log/app.log on Linux, or %LOCALAPPDATA%\neru\log\app.log on 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, then neru query hints for a hints report or neru config validate for 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 include neru --version and neru doctor output. Questions and config help belong in Discussions.

Do not answer flags or key names from memory. Run --help or read the man page first.

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: 470kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexUnverifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall