Skip to main content

Troubleshoot

A key binding is not firing​

Before assuming the binding itself is misconfigured, take a step back and check whether the keystroke is even reaching Rune. On macOS in particular, several useful combinations are claimed by the operating system before any application sees them. <ctrl-space>, for example, is bound by default to "Select the previous input source" and never makes it through to Rune, even though Rune binds it by default.

1. Disable the conflicting macOS shortcut​

For <ctrl-space> specifically:

  1. Open System Settings → Keyboard → Keyboard Shortcuts…
  2. Select Input Sources in the left pane.
  3. Uncheck Select the previous input source (and Select next source in Input menu if you also use <ctrl-option-space>).
  4. Close the dialog.

The same procedure applies to any other combination that the OS is intercepting: look under Keyboard Shortcuts, Mission Control, Spotlight, and Accessibility for shortcuts that overlap with the binding you are trying to use.

On Linux, key events are dispatched by your desktop environment, window manager, or compositor before they reach Rune. Consult the documentation for whichever component governs input on your system and remove or remap the conflicting shortcut:

  • GNOME: Settings → Keyboard → View and Customize Shortcuts.
  • KDE Plasma: System Settings → Shortcuts, and System Settings → Window Management → Window Behavior for window-level bindings.
  • Xfce: Settings → Keyboard → Application Shortcuts and Window Manager → Keyboard.
  • Tiling window managers (i3, Sway, Hyprland, dwm, …): check the relevant config file (for example ~/.config/i3/config, ~/.config/sway/config, or ~/.config/hypr/hyprland.conf) for a bindsym/bind line that claims the combination, and either remove it or rebind it.
  • Input method frameworks (IBus, Fcitx, ibus-anthy, …) also intercept keys such as <ctrl-space> for input-source switching. Disable the trigger in the framework's settings if you do not need it.

2. Confirm the keystroke reaches Rune with the keydump command​

Once the OS-level shortcut is disabled, run the keydump command inside Rune to see exactly which key events Rune receives. Press the binding you want to verify. Each keystroke that reaches Rune is printed as it is decoded. If nothing appears, the event is still being swallowed before it reaches Rune; revisit step 1 and check for window manager shortcuts that may also be claiming the combination.

tip

Press <ctrl-c> followed by <ctrl-d> to exit keydump and return to the normal prompt.

My remapped key is not honored in Rune​

If you remapped a key at the OS level (a common example is making CapsLock act as Escape) and Rune still does not respond to it, the keystroke is usually reaching Rune under its original identity rather than the remapped one.

Confirm this with the keydump command: press the key and look at what Rune reports.

  • If keydump shows the remapped key (for example, you press CapsLock and it prints <esc>), the remap is reaching Rune and any remaining problem is with the binding itself, not the remap.
  • If keydump shows the original key (you press CapsLock and it prints CapsLock, or nothing at all), Rune is reading the physical key and never sees the OS-level substitution.

In the second case, do the remap inside Rune instead, with gui.key_mapping. It runs after Rune reads the physical key, so it is not affected by whether the OS substitution reaches the application:

gui:
  key_mapping:
    "<capslock>": "<esc>"

Keys such as CapsLock, NumLock, ScrollLock, and Menu do nothing on their own in Rune; gui.key_mapping is the only way to give them an effect. See Key remapping for the full reference.

The command prompt will not open in an external editor​

When editor.mode is exo, Rune embeds a guest editor (such as vim or nvim) and forwards your keystrokes to it. If the command prompt never opens, the most likely cause is that the guest editor is swallowing the activation key before Rune can act on it.

The classic case is leaving command.key at :. Inside vim, : enters the editor's own command-line mode, so Rune never sees it and the Rune command prompt does not open. vim, nvim, Helix, and Kakoune all bind : this way, so a bare : is never a suitable command-prompt key when one of them is your guest editor. There is no safe activation key that works across every guest editor, so in exo mode you must pick one your guest editor will not capture.

The exo presets default command.key to <shift-meta-p> for exactly this reason. If you have overridden it, choose a combination that carries a meta, ctrl, or alt modifier, which guest editors rarely bind:

command:
  key: "<shift-meta-p>"

<ctrl-space> is another common choice, but note that the OS often claims it (see A key binding is not firing above). If the new key still does nothing, confirm it actually reaches Rune with the keydump command; the guest editor or the OS may be claiming it.

Ask Rune Agent