Skip to content

Keybindings

Kact captures navigation keys only while a mode is active. Built-in local controls are enabled by navigation_enabled = true. Custom maps require enabled = true. Global shortcuts need a modifier and are empty by default.

Local controls are a macOS feature. They are only captured after activate grid, activate elements, or activate freestyle; normal typing remains untouched at every other time. On X11, use an external tool to send CLI commands instead.

Action Default local key Notes
Cancel / deactivate Escape, Cmd+., Ctrl+G First cancel clears a label prefix.
Hide navigation Cmd+H Deactivates.
Select label Displayed label Grid and elements modes.
Refresh elements Ctrl+R Elements mode only.
Focus next / previous element Tab / Shift+Tab Elements mode only.
Backspace Backspace Removes one label character.
Move Arrow keys 10 points.
Move farther Alt + arrows 100 points.
Jump to edge Cmd + arrows
Scroll Shift + arrows
Click / drop drag Enter
Begin drag =
Double click </kbd>
Middle / right click [ / ]
Modified click modifiers + Enter Any non-empty Ctrl/Alt/Shift/Cmd combination.
Toggle grid lines / labels Ctrl+= / Ctrl+Shift+=
Change grid density Cmd+Shift+= / Cmd+Shift+- Larger / smaller cells.
Change contrast Cmd+= / Cmd+-

vi is the default. It adds H/J/K/L movement, Ctrl+H/J/K/L larger movement, Shift+H/J/K/L edge jumps, Shift+M center/corner cycling, and Ctrl+B/F/I/A scrolling.

emacs adds Ctrl+P/N/B/F movement, Alt+A/E/B/F larger movement, Ctrl+A/E edge jumps, Ctrl+L center/corner cycling, and Shift+P/N/B/F scrolling.

Preset Small move Large move Edge jump Scroll
vi H/J/K/L Ctrl+H/J/K/L Shift+H/J/K/L Ctrl+B/F/I/A
emacs Ctrl+P/N/B/F Alt+A/E/B/F Alt+Shift+, / Alt+Shift+. / Ctrl+A/E Shift+P/N/B/F

Keys used by local bindings are removed from the label alphabet. Kact rejects a configuration that leaves fewer than two label characters.

[keybindings]
enabled = true
[keybindings.global]
"ctrl+alt+g" = "activate grid"
[keybindings.local]
"tab" = "refine"

Binding values are Kact actions, never shell commands. They use the same syntax as the CLI reference. Custom local keys override preset keys.

Use a global map to enter a Kact mode and a local map for actions available only within that mode:

[keybindings]
enabled = true
navigation_enabled = true
preset = "vi"
[keybindings.global]
"ctrl+alt+g" = "activate grid"
"ctrl+alt+f" = "toggle freestyle"
[keybindings.local]
"tab" = "refine"
"shift+enter" = "click --modifiers shift"

If Karabiner-Elements, Hammerspoon, Kanata, or your window manager owns the shortcuts, leave custom Kact maps disabled:

[keybindings]
enabled = false
navigation_enabled = false

This command-only setup still supports every CLI action, including grid activation on macOS. It simply prevents Kact from installing a keyboard listener.