Add custom keybinding remapping for global shortcuts

Let users rebind command palette, new chat, open settings, and the
shortcuts dialog to their own key combos in Settings. Renderer-only
shortcuts are matched in JS against the saved binding; the two that
are native-menu accelerators (new chat, settings) get the menu
rebuilt with the new accelerator instead, since Electron menu
shortcuts can't be intercepted from JS.

Author: voidstackloop

app/src/keybindings.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from "vitest";
+import { bindingToAccelerator } from "./keybindings";
+
+describe("bindingToAccelerator", () => {
+    it("converts a simple mod+letter binding", () => {
+        expect(bindingToAccelerator("mod+n")).toBe("CmdOrCtrl+N");
+    });
+
+    it("converts a binding with shift and a punctuation key", () => {
+        expect(bindingToAccelerator("mod+shift+,")).toBe("CmdOrCtrl+Shift+,");
+    });
+
+    it("converts a binding with alt", () => {
+        expect(bindingToAccelerator("mod+alt+p")).toBe("CmdOrCtrl+Alt+P");
+    });
+});

app/src/keybindings.ts

@@ -0,0 +1,26 @@
+// Only actions the native Electron menu owns an accelerator for live here —
+// "New chat" and "Settings" are dispatched by the OS-level menu accelerator,
+// so rebinding them means rebuilding the menu (see menu.ts). Renderer-only
+// shortcuts (command palette, shortcuts dialog) are matched in JS instead;
+// see frontend/src/lib/keybindings.ts for those.
+export type KeybindingAction = "newChat" | "openSettings";
+
+export const DEFAULT_MENU_KEYBINDINGS: Record<KeybindingAction, string> = {
+    newChat: "mod+n",
+    openSettings: "mod+,",
+};
+
+// Converts this app's normalized binding string ("mod+shift+n") into an
+// Electron accelerator ("CmdOrCtrl+Shift+N").
+export function bindingToAccelerator(binding: string): string {
+    return binding
+        .split("+")
+        .map((part) => {
+            if (part === "mod") return "CmdOrCtrl";
+            if (part === "shift") return "Shift";
+            if (part === "alt") return "Alt";
+            if (part === "escape") return "Esc";
+            return /^[a-z]$/.test(part) ? part.toUpperCase() : part;
+        })
+        .join("+");
+}

app/src/main.ts

@@ -363,6 +363,9 @@ function registerIpcHandlers(): void {
     ipcMain.handle("settings:save", (_event: IpcMainInvokeEvent, partial) => {
         const saved = settingsStore.saveSettings(partial);
         if (partial.ollamaHost !== undefined) ollama.setHost(saved.ollamaHost);
+        if (partial.keybindings !== undefined) {
+            setupMenu(() => mainWindow, () => checkForUpdatesManually(() => mainWindow), saved.keybindings);
+        }
         return saved;
     });
 
@@ -700,7 +703,7 @@ async function connectEnabledMcpServers(): Promise<void> {
 
 app.whenReady().then(async () => {
     registerIpcHandlers();
-    setupMenu(() => mainWindow, () => checkForUpdatesManually(() => mainWindow));
+    setupMenu(() => mainWindow, () => checkForUpdatesManually(() => mainWindow), settingsStore.getSettings().keybindings);
     createWindow();
     ollama.setHost(settingsStore.getSettings().ollamaHost);
     ollama.setModelsDir(settingsStore.getSettings().modelsDir);

app/src/menu.ts

@@ -1,6 +1,12 @@
 import { app, BrowserWindow, Menu, MenuItemConstructorOptions, dialog } from "electron";
+import { DEFAULT_MENU_KEYBINDINGS, bindingToAccelerator, type KeybindingAction } from "./keybindings";
 
-export function setupMenu(getWindow: () => BrowserWindow | null, checkForUpdates: () => void): void {
+export function setupMenu(
+    getWindow: () => BrowserWindow | null,
+    checkForUpdates: () => void,
+    keybindings: Partial<Record<KeybindingAction, string>> = {}
+): void {
+    const bindings = { ...DEFAULT_MENU_KEYBINDINGS, ...keybindings };
     const isMac = process.platform === "darwin";
 
     function send(channel: string) {
@@ -40,8 +46,16 @@ export function setupMenu(getWindow: () => BrowserWindow | null, checkForUpdates
         {
             label: "File",
             submenu: [
-                { label: "New Chat", accelerator: "CmdOrCtrl+N", click: () => send("menu:new-chat") },
-                { label: "Settings", accelerator: "CmdOrCtrl+,", click: () => send("menu:open-settings") },
+                {
+                    label: "New Chat",
+                    accelerator: bindingToAccelerator(bindings.newChat),
+                    click: () => send("menu:new-chat"),
+                },
+                {
+                    label: "Settings",
+                    accelerator: bindingToAccelerator(bindings.openSettings),
+                    click: () => send("menu:open-settings"),
+                },
                 { type: "separator" },
                 isMac ? { role: "close" } : { role: "quit" },
             ],

app/src/settings-store.ts

@@ -73,6 +73,12 @@ export interface AppSettings {
     // Set once the first-run provider setup wizard has been completed (or
     // explicitly skipped), so it doesn't reappear on every launch.
     onboardingComplete?: boolean;
+    // User-remapped shortcuts, keyed by action name, normalized as
+    // "mod+shift+k" (mod = Ctrl/Cmd). Covers both menu-accelerator actions
+    // (KeybindingAction, above) and renderer-only ones the frontend matches
+    // in JS (command palette, shortcuts dialog) — this store doesn't
+    // distinguish the two, it just persists whatever the renderer sends.
+    keybindings?: Record<string, string>;
 }
 
 const DEFAULTS: AppSettings = {

frontend/src/components/keyboard-shortcuts-dialog.tsx

@@ -1,8 +1,6 @@
 import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription } from "@/components/ui/dialog";
 import { useI18n } from "@/lib/i18n";
-
-const isMac = typeof navigator !== "undefined" && /Mac|iPod|iPhone|iPad/.test(navigator.platform);
-const mod = isMac ? "⌘" : "Ctrl";
+import { DEFAULT_KEYBINDINGS, formatBindingForDisplay, type KeybindingAction } from "@/lib/keybindings";
 
 function Shortcut({ label, keys }: { label: string; keys: string[] }) {
     return (
@@ -25,9 +23,11 @@ function Shortcut({ label, keys }: { label: string; keys: string[] }) {
 export function KeyboardShortcutsDialog({
     open,
     onOpenChange,
+    keybindings = DEFAULT_KEYBINDINGS,
 }: {
     open: boolean;
     onOpenChange: (open: boolean) => void;
+    keybindings?: Record<KeybindingAction, string>;
 }) {
     const { t } = useI18n();
 
@@ -39,10 +39,10 @@ export function KeyboardShortcutsDialog({
                     <DialogDescription>{t.keyboardShortcutsHelp}</DialogDescription>
                 </DialogHeader>
                 <div className="flex flex-col divide-y divide-border">
-                    <Shortcut label={t.shortcutCommandPalette} keys={[mod, "K"]} />
-                    <Shortcut label={t.shortcutNewChat} keys={[mod, "N"]} />
-                    <Shortcut label={t.shortcutSettings} keys={[mod, ","]} />
-                    <Shortcut label={t.shortcutShowShortcuts} keys={[mod, "/"]} />
+                    <Shortcut label={t.shortcutCommandPalette} keys={[formatBindingForDisplay(keybindings.commandPalette)]} />
+                    <Shortcut label={t.shortcutNewChat} keys={[formatBindingForDisplay(keybindings.newChat)]} />
+                    <Shortcut label={t.shortcutSettings} keys={[formatBindingForDisplay(keybindings.openSettings)]} />
+                    <Shortcut label={t.shortcutShowShortcuts} keys={[formatBindingForDisplay(keybindings.showShortcuts)]} />
                     <Shortcut label={t.shortcutSend} keys={["Enter"]} />
                     <Shortcut label={t.shortcutNewline} keys={["Shift", "Enter"]} />
                     <Shortcut label={t.shortcutStopGenerating} keys={["Esc"]} />

frontend/src/components/layout.tsx

@@ -33,6 +33,7 @@ import { cn } from "@/lib/utils";
 import type { ChatOptions, ChatSession, Project, PromptPreset } from "@/types/electron";
 import { extractVariables, fillTemplate } from "@/lib/prompt-templates";
 import { PromptVariableDialog } from "@/components/prompt-variable-dialog";
+import { DEFAULT_KEYBINDINGS, matchesBinding, subscribeKeybindings, type KeybindingAction } from "@/lib/keybindings";
 
 function SessionRow({
     session,
@@ -515,12 +516,15 @@ export default function Layout() {
     const [paletteOpen, setPaletteOpen] = useState(false);
     const [shortcutsOpen, setShortcutsOpen] = useState(false);
     const [showOnboarding, setShowOnboarding] = useState(false);
+    const [keybindings, setKeybindings] = useState<Record<KeybindingAction, string>>(DEFAULT_KEYBINDINGS);
 
     useEffect(() => {
         if (!hasApi) return;
         window.api.settings.get().then((s) => {
             setShowOnboarding(!s.onboardingComplete);
+            setKeybindings({ ...DEFAULT_KEYBINDINGS, ...s.keybindings });
         });
+        return subscribeKeybindings(setKeybindings);
     }, [hasApi]);
 
     const query = search.trim().toLowerCase();
@@ -583,21 +587,24 @@ export default function Layout() {
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [hasApi]);
 
-    // Ctrl/Cmd+K opens the command palette, Ctrl/Cmd+/ shows the shortcuts
-    // cheat-sheet, both from anywhere in the app.
+    // Command palette and the shortcuts cheat-sheet are renderer-only (no
+    // native menu entry), so they're matched here against the user's
+    // (possibly remapped) bindings rather than a hardcoded key check.
+    // "New chat"/"Settings" are remapped instead by rebuilding the native
+    // menu's accelerator — see app/src/menu.ts — so they're not handled here.
     useEffect(() => {
         function onKeyDown(e: KeyboardEvent) {
-            if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "k") {
+            if (matchesBinding(e, keybindings.commandPalette)) {
                 e.preventDefault();
                 setPaletteOpen((o) => !o);
-            } else if ((e.ctrlKey || e.metaKey) && e.key === "/") {
+            } else if (matchesBinding(e, keybindings.showShortcuts)) {
                 e.preventDefault();
                 setShortcutsOpen((o) => !o);
             }
         }
         window.addEventListener("keydown", onKeyDown);
         return () => window.removeEventListener("keydown", onKeyDown);
-    }, []);
+    }, [keybindings]);
 
     async function handleDelete(e: React.MouseEvent, id: string) {
         e.stopPropagation();
@@ -762,7 +769,7 @@ export default function Layout() {
                 onNavigateSettings={() => navigate("/settings")}
                 onNavigateCompare={() => navigate("/compare")}
             />
-            <KeyboardShortcutsDialog open={shortcutsOpen} onOpenChange={setShortcutsOpen} />
+            <KeyboardShortcutsDialog open={shortcutsOpen} onOpenChange={setShortcutsOpen} keybindings={keybindings} />
             <OnboardingWizard open={showOnboarding} onDone={() => setShowOnboarding(false)} />
         </div>
     );

frontend/src/lib/keybindings.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { eventToBindingString, matchesBinding, formatBindingForDisplay } from "./keybindings";
+
+function key(overrides: Partial<{ key: string; ctrlKey: boolean; metaKey: boolean; shiftKey: boolean; altKey: boolean }>) {
+    return { key: "", ctrlKey: false, metaKey: false, shiftKey: false, altKey: false, ...overrides };
+}
+
+describe("eventToBindingString", () => {
+    it("normalizes ctrl and meta to the same 'mod' token", () => {
+        expect(eventToBindingString(key({ key: "k", ctrlKey: true }))).toBe("mod+k");
+        expect(eventToBindingString(key({ key: "k", metaKey: true }))).toBe("mod+k");
+    });
+
+    it("includes shift and alt in a fixed order", () => {
+        expect(eventToBindingString(key({ key: "p", ctrlKey: true, shiftKey: true, altKey: true }))).toBe(
+            "mod+shift+alt+p"
+        );
+    });
+
+    it("returns null for a bare modifier keypress", () => {
+        expect(eventToBindingString(key({ key: "Control", ctrlKey: true }))).toBeNull();
+    });
+});
+
+describe("matchesBinding", () => {
+    it("matches a KeyboardEvent-shaped object against a normalized binding", () => {
+        const e = { key: "k", ctrlKey: true, metaKey: false, shiftKey: false, altKey: false } as KeyboardEvent;
+        expect(matchesBinding(e, "mod+k")).toBe(true);
+        expect(matchesBinding(e, "mod+n")).toBe(false);
+    });
+});
+
+describe("formatBindingForDisplay", () => {
+    it("renders a single-letter binding in uppercase", () => {
+        expect(formatBindingForDisplay("mod+n")).toMatch(/N$/);
+    });
+});

frontend/src/lib/keybindings.ts

@@ -0,0 +1,60 @@
+export type KeybindingAction = "commandPalette" | "newChat" | "openSettings" | "showShortcuts";
+
+const isMac = typeof navigator !== "undefined" && /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+
+export const DEFAULT_KEYBINDINGS: Record<KeybindingAction, string> = {
+    commandPalette: "mod+k",
+    newChat: "mod+n",
+    openSettings: "mod+,",
+    showShortcuts: "mod+/",
+};
+
+export const KEYBINDING_ACTIONS: KeybindingAction[] = ["commandPalette", "newChat", "openSettings", "showShortcuts"];
+
+// Canonical form: modifier tokens (mod, shift, alt) in that fixed order,
+// lowercased, joined by "+", followed by the key itself. Two independently
+// captured keydowns for "the same" shortcut always normalize to the same
+// string, which is what makes them comparable/storable at all.
+export function eventToBindingString(e: { key: string; ctrlKey: boolean; metaKey: boolean; shiftKey: boolean; altKey: boolean }): string | null {
+    if (["Control", "Meta", "Shift", "Alt"].includes(e.key)) return null;
+    const parts: string[] = [];
+    if (e.ctrlKey || e.metaKey) parts.push("mod");
+    if (e.shiftKey) parts.push("shift");
+    if (e.altKey) parts.push("alt");
+    parts.push(e.key.toLowerCase());
+    return parts.join("+");
+}
+
+export function matchesBinding(e: KeyboardEvent, binding: string): boolean {
+    return eventToBindingString(e) === binding;
+}
+
+export function formatBindingForDisplay(binding: string): string {
+    return binding
+        .split("+")
+        .map((part) => {
+            if (part === "mod") return isMac ? "⌘" : "Ctrl";
+            if (part === "shift") return "Shift";
+            if (part === "alt") return isMac ? "⌥" : "Alt";
+            if (part === "escape") return "Esc";
+            return part.length === 1 ? part.toUpperCase() : part.charAt(0).toUpperCase() + part.slice(1);
+        })
+        .join(isMac ? "" : "+");
+}
+
+type Listener = (bindings: Record<KeybindingAction, string>) => void;
+const listeners = new Set<Listener>();
+
+// Settings.tsx saves keybindings while Layout's keydown handler (which
+// actually matches them) lives outside that component tree and doesn't
+// remount on navigation — a plain in-memory pub-sub is the simplest way to
+// push a change across without standing up a whole settings context just
+// for this one field.
+export function notifyKeybindingsChanged(bindings: Record<KeybindingAction, string>): void {
+    listeners.forEach((l) => l(bindings));
+}
+
+export function subscribeKeybindings(listener: Listener): () => void {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}

frontend/src/lib/translations.ts

@@ -244,6 +244,12 @@ export interface Dictionary {
     tools: string;
     noneConnected: string;
     appMemoryUsage: string;
+    keybindings: string;
+    keybindingsDescription: string;
+    pressAKey: string;
+    recordShortcut: string;
+    reset: string;
+    keybindingConflict: string;
     copied: string;
     openLogsFolder: string;
     checkForUpdates: string;
@@ -508,6 +514,12 @@ export const en: Dictionary = {
     tools: "tools",
     noneConnected: "None connected",
     appMemoryUsage: "App memory usage",
+    keybindings: "Keybindings",
+    keybindingsDescription: "Rebind the app's global shortcuts to whatever combo you'd rather use.",
+    pressAKey: "Press a key combo… (Esc to cancel)",
+    recordShortcut: "Record shortcut",
+    reset: "Reset",
+    keybindingConflict: "{key} is already used by another shortcut.",
     copyDiagnosticInfo: "Copy diagnostic info",
     copied: "Copied",
     openLogsFolder: "Open logs folder",
@@ -782,6 +794,12 @@ export const tr: Dictionary = {
     tools: "araç",
     noneConnected: "Bağlı yok",
     appMemoryUsage: "Uygulama bellek kullanımı",
+    keybindings: "Kısayol tuşları",
+    keybindingsDescription: "Uygulamanın genel kısayollarını istediğiniz tuş kombinasyonuna yeniden atayın.",
+    pressAKey: "Bir tuş kombinasyonuna basın… (İptal için Esc)",
+    recordShortcut: "Kısayolu kaydet",
+    reset: "Sıfırla",
+    keybindingConflict: "{key} zaten başka bir kısayol tarafından kullanılıyor.",
     copied: "Kopyalandı",
     openLogsFolder: "Günlük klasörünü aç",
     checkForUpdates: "Güncellemeleri denetle",