Skip to content

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.

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 menu

A [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 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-click

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

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"]

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"

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.

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. Space is allowed.
  • A label typed after a space narrows the matches to that label. save a keeps the save matches whose label starts with A, along with any text still matching save a. Once one is left, Return acts on it. With --confirm-on-label, it acts as soon as one is left, without Return. A single match by text alone still waits for Return. To turn this on only for searches opened with /, bind "/" = "action search_hints --confirm-on-label" under [hints.hotkeys].
  • Backspace deletes a character. Escape cancels 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:

MatchesWith --actionWithout --action
NoneEvery hint comes backEvery hint comes back
OneMoves the cursor to it and runs the actionMoves the cursor to it
SeveralThe matches keep their labels, so type oneMoves 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.

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

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.

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

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 = true

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

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

Enter and leave a mode with one key:

[hotkeys]
"Ctrl+F" = "grid --toggle"
"Ctrl+G" = "recursive_grid --toggle"
"Ctrl+H" = "hints --toggle"

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 start

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

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 with the jump already waiting for text, by feeding it s once it is open:

[hotkeys]
"Primary+Shift+V" = ["vim", "action feed --mode s"]

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

Start the macOS app with a specific config, such as a screen-sharing profile. ~ is not expanded, so use an absolute path:

Terminal window
open -a neru --args launch -c /absolute/path/to/your/config

Open the config the daemon uses:

Terminal window
neru status --json | jq -r .config | xargs nvim

For a new window, pass the pipeline to your terminal, such as open -na Ghostty --args -e bash -c "..." on macOS.