Recipes
Ready-to-copy configs for common goals. Add one to your config.toml, then
run neru config reload. The launcher keys are examples, so change them to
suit you.
Clicking
Section titled “Clicking”Click as soon as a hint is typed
Section titled “Click as soon as a hint is typed”Click as soon as you finish typing a hint label:
[hotkeys]"Primary+Shift+Space" = "hints --action left_click""Primary+Shift+R" = "hints --action right_click" # context menuA [hotkeys] entry that opens a mode replaces that mode’s default launcher,
listed under Global hotkeys,
rather than adding a second way in. So plain hints is gone even with only
the second line. To keep it, bind it again, such as
"Primary+Shift+H" = "hints".
Click with Return
Section titled “Click with Return”Click the selected hint with Return:
[hints.hotkeys]"Enter" = "action left_click""Shift+Enter" = "action right_click""Primary+Enter" = "action middle_click""Ctrl+Enter" = "action left_click,left_click" # double-clickA comma chain clicks several times at one point, so
"action left_click,left_click,left_click" triple-clicks. See
neru action left_click.
Click and leave the mode with one key
Section titled “Click and leave the mode with one key”Click and leave hints mode with one key. The same lines work in the other
mode tables, such as [grid.hotkeys]:
[hints.hotkeys]"Shift+L" = ["action left_click", "idle"]"Shift+R" = ["action right_click", "idle"]The mode exits even if the click fails. To stay in the mode on failure, write
"action left_click --bail-on-error". See
Failure policy.
Pause after a click
Section titled “Pause after a click”Hold the pointer still after a click, for apps such as Discord that need it:
[recursive_grid.hotkeys]# Click, wait, then reset, which moves the cursor back to the grid center"Ctrl+J" = ["action left_click", "action sleep 0.05", "action reset"]Drag with any mouse button
Section titled “Drag with any mouse button”Press a button, navigate, and release it elsewhere. Middle-drag pans the canvas in apps such as Blender, and right-drag creates shortcuts on Windows.
[recursive_grid.hotkeys]"Shift+I" = "action left_click --state down" # shipped default"Shift+U" = "action left_click --state up" # shipped default"Shift+O" = "action right_click --state down""Shift+P" = "action right_click --state up""Shift+K" = "action middle_click --state down""Shift+J" = "action middle_click --state up"For one key that presses and then releases, use
"Shift+I" = "action left_click --toggle". Escape mid-drag releases the
button.
To start a drag from a hint:
[hotkeys]"Primary+Shift+D" = "hints --action left_mouse_down"Add a shortcut for a button an app lacks
Section titled “Add a shortcut for a button an app lacks”Give a button its own key, such as Cmd+1 for the Home view in Claude for
macOS. A root-level [[app_configs]] entry applies only while that app has
focus.
If the button has unique text, filter hints to it and click the first
match with the neru-click script from
Scripting. This survives window
moves and resizes:
[[app_configs]]bundle_id = "com.anthropic.claudefordesktop"hotkeys = { "Cmd+1" = "exec ~/.local/bin/neru-click --role button --text Home" }The script asks neru query hints for the label instead of assuming one,
because Neru assigns labels afresh on every scan. See
neru query. A common word can match other
buttons too, such as “Code” matching every “Copy code” button.
Otherwise, click at an offset from the window’s top-left corner. This survives window moves, but not layout changes. Define the steps once as a macro, then bind each button by its offset:
[macros]window_click = [ "action move_mouse --window --x -1000 --y -1000", # clamps to the top-left corner "action sleep 0.1", "action move_mouse_relative --dx $1 --dy $2", "action sleep 0.1", "action left_click",]
[[app_configs]]bundle_id = "com.anthropic.claudefordesktop"hotkeys = { "Cmd+1" = "macro window_click 100 70", "Cmd+2" = "macro window_click 250 70", "Cmd+3" = "macro window_click 400 70"}Get each offset by subtracting the window’s top-left corner from the button’s
screen position. For a window that never moves, action move_mouse --x 113 --y 123
with absolute coordinates also works.
Search hints by text
Section titled “Search hints by text”Filter hints by element text. Press / (action search_hints) in hints mode,
or open hints with search showing:
[hotkeys]"Primary+Shift+Space" = "hints --search"- Typing filters by element title, description or value.
Spaceis allowed. - A label typed after a space narrows the matches to that label.
save akeeps thesavematches whose label starts withA, along with any text still matchingsave a. Once one is left,Returnacts on it. With--confirm-on-label, it acts as soon as one is left, withoutReturn. A single match by text alone still waits forReturn. To turn this on only for searches opened with/, bind"/" = "action search_hints --confirm-on-label"under[hints.hotkeys]. Backspacedeletes a character.Escapecancels and restores every hint.Tab(action cycle_hint) moves between matches without running the action.
Return closes the search. What else it does depends on the matches:
| Matches | With --action | Without --action |
|---|---|---|
| None | Every hint comes back | Every hint comes back |
| One | Moves the cursor to it and runs the action | Moves the cursor to it |
| Several | The matches keep their labels, so type one | Moves the cursor to the first match |
Search needs element text, so it does not work with the contour or segment
strategy.
Wait for a page to load before hints redraw
Section titled “Wait for a page to load before hints redraw”Wait for the page to update after a click before hints redraw, in one app only:
[[hints.app_configs]]bundle_id = "com.brave.Browser"hotkeys = { "Return" = ["action left_click", "action sleep 0.8", "hints"], "Shift+L" = "__disabled__"}These keys merge over [hints.hotkeys] for Brave only. Other modes’
app_configs work the same way.
Inspect an app’s accessibility tree (macOS)
Section titled “Inspect an app’s accessibility tree (macOS)”Find an element’s role and text for clickable_roles or --role with one of:
- UIElementInspector, an Apple sample app that needs no Xcode: UIElementInspector.zip
- Accessibility Inspector: Xcode > Open Developer Tool > Accessibility Inspector
neru roles maps Neru’s role names to the platform’s.
Cursor
Section titled “Cursor”Put the cursor back after a click
Section titled “Put the cursor back after a click”Return the cursor to where it was after hints clicks:
[hotkeys]"Primary+Shift+Space" = ["action save_cursor_pos", "hints"]
[hints.hotkeys]"Enter" = ["action left_click", "idle", "action restore_cursor_pos"]When the click comes from the mode’s --action, use the repeatable
--on-exit flag:
[hotkeys]"Primary+Shift+Space" = [ "action save_cursor_pos", "hints --action left_click --on-exit 'action restore_cursor_pos'",]--on-exit runs only after the action, so Escape leaves the cursor where you
moved it. Use --slot to keep two saved positions apart. See
Cursor slots.
Keep the cursor still while you aim
Section titled “Keep the cursor still while you aim”Keep the pointer still while you refine a selection, for menus that close when the pointer leaves:
[hotkeys]"Primary+Shift+G" = "grid --cursor-selection-mode hold""Primary+Shift+C" = "recursive_grid --cursor-selection-mode hold"
[recursive_grid.hotkeys]"Return" = "action left_click"Click and scroll actions act on the selection, and move the pointer only then.
Add --bare to act at the real cursor. The default ` binding,
toggle-cursor-follow-selection, switches between hold and follow.
Open recursive grid already zoomed in
Section titled “Open recursive grid already zoomed in”Open recursive grid already drilled down at the cursor:
[hotkeys]"Primary+Shift+2" = "recursive_grid --zoom-to-depth 2""Primary+Shift+3" = "recursive_grid --zoom-to-depth 3 --action left_click"A depth beyond the deepest level stops at that level.
Snapping
Section titled “Snapping”neru action snap moves the cursor
onto the nearest element hints would label, without drawing labels. After a
grid gets you close, one snap lands on a small target without zooming
further.
Land a grid selection on the element
Section titled “Land a grid selection on the element”Zoom with recursive grid, then snap to the element inside the cell, and click it with a second key:
[recursive_grid.hotkeys]"Tab" = "action snap""Shift+Tab" = ["action snap", "action left_click"]Snap searches only the region you zoomed into and leaves the mode open, so
Shift+L still clicks afterwards. The same lines work in [grid.hotkeys]
once a full label picks a cell, with or without the subgrid, and in
[bisect.hotkeys] after a cut. When snap finds nothing, Shift+Tab still
clicks, at the grid’s selection, so the key works the same with or without an
element to snap to. To skip the click
instead, write "action snap --bail-on-error".
Walk from element to element
Section titled “Walk from element to element”Step through a toolbar or a list with four keys, and keep walking while one is held:
[hotkeys]"Primary+Alt+Shift+H" = "action snap --direction left""Primary+Alt+Shift+J" = "action snap --direction down""Primary+Alt+Shift+K" = "action snap --direction up""Primary+Alt+Shift+L" = "action snap --direction right"
[held_repeat]enabled = trueA step keeps to the same row or column before it jumps to a nearer element
beside it, and never lands on the container around the current element. Avoid
Primary+Alt+H on macOS, where Cmd+Option+H hides every other app.
Jump to the nearest input
Section titled “Jump to the nearest input”Put the cursor in the nearest text field, or on the nearest button named Save:
[hotkeys]"Primary+Alt+Shift+I" = ["action snap --role text_field", "action left_click"]"Primary+Alt+Shift+S" = "action snap --text Save"--role and --text take the values hints mode does. Quote a term with a
space, as in --text 'Save As'.
Modes and hotkeys
Section titled “Modes and hotkeys”Toggle a mode with one key
Section titled “Toggle a mode with one key”Enter and leave a mode with one key:
[hotkeys]"Ctrl+F" = "grid --toggle""Ctrl+G" = "recursive_grid --toggle""Ctrl+H" = "hints --toggle"Cycle through modes with one key
Section titled “Cycle through modes with one key”Step through hints, recursive grid, grid, bisect and scroll with one key.
Inside a mode, its [<mode>.hotkeys] binding wins over the global one, so
every mode in the cycle needs an entry. See
Resolution order.
[hotkeys]"Primary+Ctrl+F" = "hints" # from idle
[hints.hotkeys]"Primary+Ctrl+F" = "recursive_grid"
[recursive_grid.hotkeys]"Primary+Ctrl+F" = "grid"
[grid.hotkeys]"Primary+Ctrl+F" = "bisect"
[bisect.hotkeys]"Primary+Ctrl+F" = "scroll"
[scroll.hotkeys]"Primary+Ctrl+F" = "hints" # wrap back to the startEscape still returns to idle. The [hotkeys] line replaces the default
hints launcher. The other modes keep theirs, listed under
Global hotkeys, and setting one
to "__disabled__" removes it.
Switch grid layouts with one key
Section titled “Switch grid layouts with one key”Swap recursive grid layouts. --no-reload defers the reload to the last step:
[hotkeys]"Cmd+8" = [ "config set recursive_grid.grid_cols 3 --no-reload", "config set recursive_grid.grid_rows 3 --no-reload", "config set recursive_grid.keys gcrhtnmwv",]"Cmd+9" = [ "config reset recursive_grid.grid_cols --no-reload", "config reset recursive_grid.grid_rows --no-reload", "config reset recursive_grid.keys",]config set values persist in the override file. See
Configuring Neru.
Open vim mode straight into a jump
Section titled “Open vim mode straight into a jump”Open vim mode with the jump already waiting for text, by feeding it s
once it is open:
[hotkeys]"Primary+Shift+V" = ["vim", "action feed --mode s"]Read the screen again before each jump
Section titled “Read the screen again before each jump”Have s read the screen first, so the jump searches the page as it is now
rather than as it was when vim mode opened:
[vim.keymaps.normal]"s" = "<Plug>(read-screen)<Plug>(jump)"See vim keymaps for the other commands a mapping can run.
Leave global hotkeys to another tool
Section titled “Leave global hotkeys to another tool”Leave global bindings to an external daemon such as skhd. An empty [hotkeys]
table clears every default global hotkey:
[hotkeys]Each [<mode>.hotkeys] stays. Trigger modes with neru hints, neru grid and
so on, as in Scripting.
Config files
Section titled “Config files”Launch the macOS app with another config
Section titled “Launch the macOS app with another config”Start the macOS app with a specific config, such as a screen-sharing profile.
~ is not expanded, so use an absolute path:
open -a neru --args launch -c /absolute/path/to/your/configOpen the config the daemon is using
Section titled “Open the config the daemon is using”Open the config the daemon uses:
neru status --json | jq -r .config | xargs nvimFor a new window, pass the pipeline to your terminal, such as
open -na Ghostty --args -e bash -c "..." on macOS.