Customising keybindings

Rebind any shortcut. Chord sequences supported. Reserved combos blocked. Survives reload.

Open the editor

⌘K ⌘S (chord) opens the keybindings pane in Settings. Or Settings → Keybindings.

Layout

A list of every binding, grouped by category:

  • Editor (cursor, file, formatting)
  • Project (load, scan, switch)
  • Agent (run, cancel, history)
  • View (toggle panels, fullscreen)
  • Theme

Each row shows: action name · current binding · Rebind · Reset.

A search field at the top filters by action name or current binding.

Rebind

Click Rebind on a row. A modal opens:

> Press the new keystroke (3s timeout — Esc to cancel)

Press your desired combination. Modal closes, the binding updates, persists immediately.

Chord sequences

Two-stroke sequences supported, e.g. ⌘K ⌘S. Press the first chord, the modal stays open showing "→ press the second", then capture.

The window between the two chords is 1.2 s. After that, the first chord stands alone.

Conflicts

If your new binding collides with an existing action, the modal warns:

> Conflicts with: Open Settings (⌘,)

You can:

  • Keep both — your action will trigger when the other doesn't capture (rare; usually the first registered wins).
  • Override — clears the other binding, sets yours.
  • Cancel — keeps the original.

Reserved combos

Browser-reserved combinations cannot be rebound:

⌘W · ⌘T · ⌘R · ⌘N · ⌘Q · ⌘L · ⌘+ · ⌘- · F5 · F11

The modal blocks these with a clear message.

Reset

Each row has its own Reset to clear the override and restore the default. The header has a Reset all for nuclear restore.

Persistence

Overrides are stored in two places:

  1. localStorage["kf.keybindings.overrides"] — for this device.
  2. POST /api/agent/prefs/keybindings — for cross-device sync (when logged in).

On boot, server prefs override local prefs.

Cheat sheet

? (when not in an input) opens a full overlay listing every active binding, grouped, searchable, with a "Try it" button next to each that triggers the action so you can verify.

Programmatic registration

Self-hosters can add new actions via static/js/keybindings-registry.js:

KFKeys.register({
  id: "myteam.fancy.action",
  label: "Run Fancy Action",
  defaultBinding: "⌘⇧F",
  handler: () => { /* … */ }
});

The new action appears in the editor alongside built-ins.