feat: configurable keyboard shortcuts

[Basit-Balogun10]

Problem

Users cannot remap keyboard shortcuts to suit their workflow or resolve conflicts with OS/app bindings on their machine. Closes #300

Changes

Core store (keybindingsStore.ts)

Persisted Zustand store backed by electronStorage — bindings survive app restarts. Stores custom overrides as Partial<Record<ConfigurableShortcutId, string[]>>.

• addKeybinding / updateKeybinding / removeKeybinding — per-binding CRUD, max 2 custom bindings per shortcut
• resetShortcut / resetAll — revert one or all shortcuts to defaults
• resolveKey — falls back to the static default when no custom entry exists
• splitBindings — splits comma-separated binding strings while correctly handling mod+, (the Settings shortcut key contains a literal comma — uses negative lookbehind regex (?<!\+), to distinguish separator commas from key commas)
• findConflict — checks the candidate key against all other configurable shortcuts (with live overrides applied) and all non-configurable static shortcuts; returns the conflicting description and whether it is a fixed shortcut

Definitions (keyboard-shortcuts.ts)

• 20 of 28 shortcuts marked configurable: true with an explicit CONFIGURABLE_SHORTCUT_IDS array and DEFAULT_KEYBINDINGS record
• eventToCombo — converts a KeyboardEvent to a normalised combo string (mod+shift+v); requires at least one non-shift modifier; normalises ArrowUp → up etc.
• tiptapEventToCombo — like eventToCombo but also accepts shift-only combos, needed for prompt-history-prev/next whose defaults are shift+up / shift+down
• Platform-aware display formatting throughout: Mac shows ⌘⇧⌥↩↑↓, Windows shows Ctrl+Shift+Alt+Enter+↑+↓. This also fixed a bug where hardcoded shortcut labels in the editor (e.g. the paste-as-file hint toast) were showing the Mac ⌘ symbol on Windows instead of Ctrl

Shortcut recorder UI (ShortcutRecorder.tsx)

ShortcutRecordingModal — a fullscreen capture overlay:

• Window-level keydown listener (no element focus required)
• Live conflict detection with amber highlight and description message
• Enter to confirm (blocked when conflict exists), Escape to cancel, click-backdrop to dismiss
• Title changes between "Add new binding for…" and "Edit binding for…" depending on mode

BindingChip — individual keycap with left-click to edit, right-click context menu:

• Edit binding / Add another binding / Remove binding / Reset to default
• "Remove binding" disabled (with tooltip) when it is the only binding
• "Reset to default" disabled (with tooltip) when already at default

ShortcutRecorder — row-level component:

• Multi-chip display with "or" separator; splits multi-binding defaults (e.g. mod+n,mod+t) into individual chips
• canAddMore based on custom count only — defaults don't consume the 2-binding budget
• Removing a default binding materialises the remaining defaults as custom, so sibling defaults are not lost
• Editing a default preserves all other defaults — updateKeybinding copies them into the custom array before replacing only the target

Shortcuts sheet (KeyboardShortcutsSheet.tsx)

• Self-referential header: shows the current live binding used to open the sheet itself
• Configurable rows render ShortcutRecorder; non-configurable rows render static ShortcutKeys with a "This shortcut cannot be customized" tooltip on hover
• Sticky "Reset all shortcuts to defaults" footer — only rendered when there are any customisations
• Searchable: a search bar auto-focuses when the sheet opens; supports two modes simultaneously
  • Text mode: type any characters to filter by shortcut name or context label (e.g. "task", "editor")
  • Combo mode: press any key combination with a modifier while the input is focused to filter by binding — e.g. hold Ctrl+Shift to see all shortcuts using that prefix, press Ctrl+Shift+N to isolate the exact binding; keycap chips display the captured combo in real time with a … pulse indicator for partial (modifier-only) captures
  • Pressing Backspace or any printable character while in combo mode exits combo mode and switches to text search
  • "No shortcuts found" empty state when filters match nothing

Editor integration (useTiptapEditor.ts)

• paste-as-file reads from the store dynamically; supports multiple bindings
• prompt-history-prev/next resolved from store via tiptapEventToCombo; replaces the old hardcoded event.shiftKey check
• Paste hint toast shows the live current paste-as-file binding (was hardcoded mod+shift+v)

Non-configurable shortcuts — decisions

Shortcut	Reason
Switch to task 1–9 (mod+1-9)	Range binding across 9 keys; not representable as a single bindable combo
Switch to tab 1–9 (ctrl+1-9)	Same
Find in conversation (mod+f)	Integrated with the browser find mechanism
Bold / Italic / Underline / Code (mod+b/i/u/e)	Tiptap ProseMirror commands — rebinding requires patching Tiptap extension keymaps, not just the app hotkey system

How did you test this?

Unit tests — 30 tests in keybindingsStore.test.ts covering: resolveKey, addKeybinding (dedup, max-limit enforcement), removeKeybinding, resetShortcut, resetAll, getKey, updateKeybinding (editing a default preserves siblings, editing custom replaces only target), and findConflict (configurable defaults, custom overrides on other shortcuts, non-configurable fixed shortcuts, mod+, edge case, excluded shortcut own key not flagged as conflict). All 30 pass.

Typecheck — clean (tsc --noEmit on both tsconfig.node.json and tsconfig.web.json).

E2E tests (shortcuts.spec.ts) — wrote a full E2E suite covering:

• Sheet opens, all categories visible
• Configurable chips clickable; non-configurable shows tooltip on hover
• Recording modal: opens on click, Escape cancels, backdrop click cancels, bare letter ignored, Enter without combo does nothing
• Saving: valid combo + Enter saves and modal closes
• Right-click context menu: Edit / Add another / Remove / Reset
• Add second binding; Add another disappears at 2-binding limit
• Conflict detection: amber message shown, Enter blocked, resolving conflict re-enables save
• Remove binding; Remove disabled (with tooltip) when only one binding remains
• Reset to default; Reset disabled when already at default
• Reset all: hidden with no custom bindings, appears after add, clears all on click
• Search by text: typing "task" filters to only task-related shortcuts across all categories
• Combo search: holding Ctrl+Shift narrows to all Ctrl+Shift+… shortcuts; pressing a final key (e.g. N) isolates the exact match
• Backspace / printable key in combo mode exits combo mode

Manual testing:

1. Open the Keyboard Shortcuts Sheet

Default shortcut: Cmd+/ (Mac) / Ctrl+/ (Windows)

• Press the shortcut. The "Keyboard Combos" sheet opens.

---

2. The Sheet Layout — Configurable vs Fixed

Scroll through all four categories: General, Navigation, Panels & Tabs, Editor.

Configurable rows (20 shortcuts) show interactive keycap chips you can click.
Fixed rows (8 shortcuts) show static chips. Hover one — tooltip reads "This shortcut cannot be customized."

Fixed shortcuts and why:

Shortcut	Keys	Reason non-configurable
Switch to task 1-9	Mod+1-9	Range binding, not a single key
Switch to tab 1-9	Ctrl+1-9	Range binding
Find in conversation	Mod+F	Tight browser find integration
Bold / Italic / Underline / Inline code	Mod+B/I/U/E	Tiptap rich-text internals, hardwired into editor command system

configurable-vs-fixed-shortcuts-posthog-code-configurable-shortcuts.mp4

---

3. Edit a Shortcut — Click to Edit

1. In General, find "Open command menu" (Cmd+K / Ctrl+K).
2. Left-click the keycap chip. A recording modal appears with a blurred backdrop.
3. Press any key combination, e.g. Cmd+Shift+P. The modal shows the combo formatted with platform symbols (Mac: ⌘⇧P, Windows: Ctrl+Shift+P).
4. The instruction reads "Press Enter to confirm, Escape to cancel."
5. Press Enter to save. The chip in the sheet updates immediately.
6. Dismiss the sheet. Press your new shortcut — the command menu opens. ✅

editing-a-shortcut-posthog-code-configurable-shortcuts.mp4.mp4

---

4. Conflict Detection — Amber Warning

1. Open the sheet, click a shortcut chip to edit it.
2. Press a key that is already used — e.g. Cmd+N (which is "New task").
3. The modal turns amber: the input field highlights in amber, and below reads "Conflicts with 'New task' — press a different combination."
4. While conflicting, pressing Enter does nothing — you cannot save a conflicting binding.
5. Press a different combo to clear the conflict. Press Enter to save.

Edge case — mod+, (Settings): The comma is also the separator character used internally. Try to bind Cmd+, to something — it correctly detects it conflicts with "Open settings" despite the comma in the key name.

Non-configurable conflict: Try to bind Mod+B (Bold, which is a fixed Tiptap shortcut). The conflict detection catches this too — you will see it warns "Conflicts with 'Bold'."

conflict-detection-posthog-code-configurable-shortcuts.mp4.mp4.mp4

---

5. Escape / Backdrop to Cancel

1. Open the recording modal.
2. Press Escape — modal closes without saving.
3. Open it again, press a valid combo.
4. Click the backdrop (outside the modal card) — modal closes without saving.

escape-to-cancel-posthog-code-configurable-shortcuts.mp4.mp4.mp4

---

6. Add a Second Binding (Up to 2 Custom Bindings)

1. Open the sheet. Find "New task."
2. Right-click its chip → "Add another binding."
3. Record a new key, e.g. Cmd+Shift+N. Press Enter.
4. The row now shows two chips: Cmd+N or Cmd+Shift+N (separated by "or").
5. Both trigger "New task" in the app.
6. Right-click the first chip → "Add another binding" — this option is gone because you are now at the 2-binding limit.

adding-a-second-binding-posthog-code-configurable-shortcuts.mp4.mp4

---

7. Default Shortcuts with Multiple Bindings

Some shortcuts ship with 2 default bindings (e.g. New task: Cmd+N or Cmd+T).

1. Find "New task" at its defaults.
2. Notice both chips show independently.
3. Remove one default chip (right-click → Remove binding). Only the other default remains.
4. This works by materialising the remaining defaults as custom bindings — so removing Cmd+N stores ["mod+t"] in the custom array. The other default is preserved.
5. Reset to default on either chip restores both Cmd+N and Cmd+T together.

default-shortcuts-with-multiple-binding-posthog-code-configurable-shortcuts.mp4

---

8. Edit One Default Binding — Preserves the Other

1. Reset "New task" to defaults (both Cmd+N and Cmd+T chips visible).
2. Left-click Cmd+N to edit it. Record Cmd+Shift+X. Press Enter.
3. The row now shows Cmd+Shift+X or Cmd+T — only the edited key changed, the sibling default (Cmd+T) is preserved.

Uploading editing-one-default-binding-posthog-code-configurable-shortcuts.mp4…

---

9. Reset ALL Shortcuts

1. Customise a few shortcuts across categories.
2. At the bottom of the sheet, a sticky footer appears: "Reset all shortcuts to defaults" button (only visible when there are any customisations).
3. Click it — all bindings reset. The footer disappears.

resetting-all-shortcuts-posthog-code-configurable-shortcuts.mp4

---

10. Paste-as-File Shortcut (Configurable, Live Hint)

In the Editor category, find "Paste as file attachment" (Cmd+Shift+V / Ctrl+Shift+V).

1. Copy some text to clipboard.
2. In the message editor, paste normally — if text > 200 chars, a toast appears: "Use Ctrl+Shift+V to paste as a file attachment instead." (shows the live current binding).
3. Open the sheet and change the paste-as-file shortcut to Ctrl+Shift+G.
4. Paste again — the toast now reads "Use Ctrl+Shift+G to paste as a file attachment instead." ✅

paste-as-file-shortcut-posthog-code-configurable-shortcuts.mp4

---

11. Persistence Across App Restarts

1. Customise several shortcuts.
2. Quit and relaunch the app.
3. All customisations are preserved — stored via electronStorage (Electron user data directory).

---

12. Search the Shortcuts Sheet

The search bar auto-focuses when the sheet opens — no click needed.

Text search:

1. Type "task" — only task-related shortcuts remain visible across all categories.
2. Type "editor" — filters to shortcuts whose context label includes "editor".
3. Click the × button to clear — full list restores.

Combo search:

1. With the search input focused, hold Ctrl (Windows) / Cmd (Mac) — the input shows a Ctrl keycap chip and the list narrows to all shortcuts that use Ctrl+….
2. While still holding, add Shift — the chip updates to Ctrl Shift and the list narrows further to Ctrl+Shift+… shortcuts.
3. Press N — the chip shows Ctrl Shift N and only "New task" remains (if at default).
4. Try Ctrl+/ — only "Show keyboard shortcuts" is shown. Try Ctrl+Shift+V — only "Paste as file attachment."

Exit combo mode:

1. While combo chips are shown, press Backspace — chips clear and the input returns to empty text mode.
2. Enter combo mode again, then type the letter t — combo chips disappear and text search activates with "t" already in the input.
3. Or click the × button at any time to clear.

Empty state:

1. Search for "zzzz" — "No shortcuts found" appears.
2. Click × or press Backspace to clear — the full list returns.

Publish to changelog?

Probably? Users can now remap any of the 20 configurable shortcuts directly inside the app via the Keyboard Shortcuts sheet (⌘/ / Ctrl+/) - and potentially any new additions to the app shortcuts can now be configurable

[greptile-apps]

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
apps/code/src/renderer/stores/keybindingsStore.ts:118-121
`updateKeybinding` does not deduplicate the result, so editing one binding to a value that already exists as another binding for the same shortcut silently produces `["ctrl+q", "ctrl+q"]`. The conflict-detection in the recording modal excludes the shortcut being edited (the `excludeId` skip), so the duplicate slips through undetected. The UI then renders two chips with identical `key` props, producing a React duplicate-key warning and potentially broken reconciliation.

```suggestion
        const updated = base.map((k) => (k === oldKey ? newKey : k));
        // Deduplicate in case newKey already exists elsewhere in the array.
        const deduped = [...new Set(updated)];
        set({
          customKeybindings: { ...get().customKeybindings, [id]: deduped },
        });
```

### Issue 2 of 2
apps/code/src/renderer/features/message-editor/tiptap/useTiptapEditor.ts:326-365
`prompt-history-prev/next` shortcuts silently break when remapped to non-arrow-key combos. The outer `event.key === "ArrowUp"` / `event.key === "ArrowDown"` guards are still hardcoded, so `forcePrev`/`forceNext` can be `true` from the store but the handler never fires unless the physical key is an arrow. A user who remaps `prompt-history-prev` to e.g. `ctrl+k` gets a chip in the UI that saves correctly but does nothing when pressed.

_{Reviews (1): Last reviewed commit: "feat: make prompt-history shortcuts conf..." | Re-trigger Greptile}

[Basit-Balogun10]

Hi @adboio! This has been sitting for a few weeks now - would appreciate a look when you get a chance (or anyone else available), many thanks!!

[jonathanlab]

Thanks a lot for this PR! I love how you can search by keystrokes. I've encountered some bugs while testing:

• Pressing Control on a MacOS keyboard while capturing a shortcut will convert it to CMD instead.
• A key combination can only start with the CMD/Control/Option key, not the shift key.

Other feedback:

• You can currently not see the combination you are recording until you are finished, which does not feel nice to use.
• The keycap component have a effect on press but this feels confusing as clicking the keycap does not always do something, since not all shortcuts are editable. Let's get rid of the effect. Instead, just offer a "pencil" icon next to editable shortcuts on hover.
• I'm missing a way to completely unassign a keybind.
• Besides resetting all shortcuts to default, you should also be able to reset individual shortcuts to their default value
• I do not think we need an entire modal for this operation. I think instead we can make the shortcut input box inline, when you click on an editable shortcut.

[jonathanlab]

This is now dead/duplicated, see KeyboardShortcutsSheet.tsx

[Basit-Balogun10]

Yea, figured. Now using features/command/KeyboardShortcutsSheet.tsx. I should revert the changes applied here though

Or do we just remove the file completely (from this PR)?

[jonathanlab]

This should not live in primitives

[jonathanlab]

?

[Basit-Balogun10]

Oh, shoot! Windows encoding corruption from conflcits resolutions, thanks. Will amend

[Basit-Balogun10]

Oh! Thanks for all of that @jonathanlab

Will be taking a look.

To remove a keybinding or reset individual shortcuts to default, there's a context menu that pops upon right-clicking each binding. Lmk if that works though

Thank you, will revert

[Basit-Balogun10]

Oh, and while I have your attention @jonathanlab
Could you help take a look at #2355 and #2361 whenever you have moment?!