Add global keyboard shortcut preference (#371)

* feat: add global keyboard shortcut preference

* fix: clarify shortcut preference behavior

Author: parsakhaz

frontend/src/App.tsx

@@ -108,6 +108,7 @@ function App() {
   const [resumableSessions, setResumableSessions] = useState<ResumableSession[]>([]);
   const [isResumeDialogOpen, setIsResumeDialogOpen] = useState(false);
   const [isHelpOpen, setIsHelpOpen] = useState(false);
+  const [isKeyboardShortcutsOpen, setIsKeyboardShortcutsOpen] = useState(false);
   const [isDocsOpen, setIsDocsOpen] = useState(false);
   const [showCreateSessionDialog, setShowCreateSessionDialog] = useState(false);
   const [showAddProjectDialog, setShowAddProjectDialog] = useState(false);
@@ -825,6 +826,10 @@ function App() {
           onCategoryChange={setSettingsCategory}
           openRequest={settingsOpenRequest}
           onOpenRequestHandled={() => setSettingsOpenRequest(undefined)}
+          onShowKeyboardShortcuts={() => {
+            closeSettings();
+            setIsKeyboardShortcutsOpen(true);
+          }}
         />
         <AnalyticsConsentDialog
           isOpen={isAnalyticsConsentOpen}
@@ -891,6 +896,11 @@ function App() {
           onClose={() => setShowAddProjectDialog(false)}
         />
         <Help isOpen={isHelpOpen} onClose={() => setIsHelpOpen(false)} />
+        <Help
+          isOpen={isKeyboardShortcutsOpen}
+          onClose={() => setIsKeyboardShortcutsOpen(false)}
+          shortcutsOnly
+        />
         <DocsDialog isOpen={isDocsOpen} onClose={() => setIsDocsOpen(false)} />
         <ShortcutHintsOverlay isVisible={shortcutHintsVisible} shortcuts={terminalShortcuts} />
         </div>

frontend/src/components/CommitDialog.tsx

@@ -4,6 +4,7 @@ import { formatKeyDisplay } from '../utils/hotkeyUtils';
 import { Modal, ModalHeader, ModalBody, ModalFooter } from './ui/Modal';
 import { Button } from './ui/Button';
 import { Textarea } from './ui/Textarea';
+import { areKeyboardShortcutsEnabled, useConfigStore } from '../stores/configStore';
 
 interface CommitDialogProps {
   isOpen: boolean;
@@ -22,6 +23,7 @@ export const CommitDialog: React.FC<CommitDialogProps> = ({
   const [isCommitting, setIsCommitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const keyboardShortcutsEnabled = useConfigStore((state) => areKeyboardShortcutsEnabled(state.config));
 
   // Set default message
   useEffect(() => {
@@ -59,13 +61,13 @@ export const CommitDialog: React.FC<CommitDialogProps> = ({
   }, [commitMessage, onCommit, onClose]);
 
   const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
-    if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
+    if (keyboardShortcutsEnabled && e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
       e.preventDefault();
       handleCommit();
     } else if (e.key === 'Escape') {
       onClose();
     }
-  }, [handleCommit, onClose]);
+  }, [handleCommit, keyboardShortcutsEnabled, onClose]);
 
   return (
     <Modal isOpen={isOpen} onClose={onClose} size="md">
@@ -116,4 +118,4 @@ export const CommitDialog: React.FC<CommitDialogProps> = ({
       </ModalFooter>
     </Modal>
   );
-};
+};

frontend/src/components/CreateSessionDialog.tsx

@@ -10,6 +10,7 @@ import { Button } from './ui/Button';
 import { Input } from './ui/Input';
 import { useSessionPreferencesStore, type SessionCreationPreferences } from '../stores/sessionPreferencesStore';
 import { useSessionStore } from '../stores/sessionStore';
+import { areKeyboardShortcutsEnabled, useConfigStore } from '../stores/configStore';
 import { generatePaneName, sanitizePaneName } from '../utils/paneName';
 
 // Interface for branch information
@@ -72,6 +73,7 @@ export function CreateSessionDialog({
   const { showError } = useErrorStore();
   const { preferences, loadPreferences, updatePreferences } = useSessionPreferencesStore();
   const existingSessions = useSessionStore(state => state.sessions);
+  const keyboardShortcutsEnabled = useConfigStore((state) => areKeyboardShortcutsEnabled(state.config));
 
   // Load session creation preferences when dialog opens
   useEffect(() => {
@@ -267,7 +269,7 @@ export function CreateSessionDialog({
       if (!isOpen) return;
 
       // Cmd/Ctrl + Enter to submit
-      if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') {
+      if (keyboardShortcutsEnabled && (e.metaKey || e.ctrlKey) && e.key === 'Enter') {
         e.preventDefault();
         const form = document.getElementById('create-session-form') as HTMLFormElement;
         if (form) {
@@ -279,7 +281,7 @@ export function CreateSessionDialog({
 
     window.addEventListener('keydown', handleKeyDown);
     return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [isOpen]);
+  }, [isOpen, keyboardShortcutsEnabled]);
 
   // Auto-focus name input on dialog open (always available immediately)
   useEffect(() => {

frontend/src/components/Help.tsx

@@ -65,13 +65,17 @@ function KeyboardShortcutsSection() {
 interface HelpProps {
   isOpen: boolean;
   onClose: () => void;
+  shortcutsOnly?: boolean;
 }
 
-export default function Help({ isOpen, onClose }: HelpProps) {
+export default function Help({ isOpen, onClose, shortcutsOnly = false }: HelpProps) {
   return (
     <Modal isOpen={isOpen} onClose={onClose} size="xl" showCloseButton={false}>
-      <ModalHeader title="Pane Help" />
+      <ModalHeader title={shortcutsOnly ? 'Keyboard Shortcuts' : 'Pane Help'} />
       <ModalBody>
+        {shortcutsOnly ? (
+          <KeyboardShortcutsSection />
+        ) : (
         <div className="space-y-8">
             {/* Quick Start */}
             <section>
@@ -286,7 +290,8 @@ export default function Help({ isOpen, onClose }: HelpProps) {
                 <li>Enable notifications to know when Claude needs your input</li>
               </ul>
             </section>
-          </div>
+        </div>
+        )}
       </ModalBody>
 
       <div className="p-4 border-t border-border-primary text-center text-sm text-text-muted">

frontend/src/components/Settings.tsx

@@ -42,9 +42,10 @@ interface SettingsProps {
   onCategoryChange: (category: SettingsCategoryId) => void;
   openRequest?: SettingsOpenRequest;
   onOpenRequestHandled: () => void;
+  onShowKeyboardShortcuts: () => void;
 }
 
-export function Settings({ isOpen, onClose, category, onCategoryChange, openRequest, onOpenRequestHandled }: SettingsProps) {
+export function Settings({ isOpen, onClose, category, onCategoryChange, openRequest, onOpenRequestHandled, onShowKeyboardShortcuts }: SettingsProps) {
   const persistence = useSettingsPersistence(isOpen);
   const dirtyForms = useDirtySettingsForms();
   const {
@@ -114,6 +115,10 @@ export function Settings({ isOpen, onClose, category, onCategoryChange, openRequ
     });
   }, [onClose, requestTransition]);
 
+  const showKeyboardShortcuts = useCallback(() => {
+    requestTransition(onShowKeyboardShortcuts);
+  }, [onShowKeyboardShortcuts, requestTransition]);
+
   const openRemoteSubview = useCallback((subview: RemoteAccessSubviewId) => {
     requestTransition(() => setRemoteSubview(subview));
   }, [requestTransition]);
@@ -141,7 +146,7 @@ export function Settings({ isOpen, onClose, category, onCategoryChange, openRequ
       case 'integrations':
         return <IntegrationsSettings persistence={persistence} {...sharedDirtyProps} />;
       case 'shortcuts':
-        return <ShortcutsSettings persistence={persistence} {...sharedDirtyProps} />;
+        return <ShortcutsSettings persistence={persistence} onShowKeyboardShortcuts={showKeyboardShortcuts} {...sharedDirtyProps} />;
       case 'privacy':
         return <PrivacySettings persistence={persistence} />;
       case 'advanced':

frontend/src/components/panels/TerminalPanel.tsx

@@ -11,7 +11,7 @@ import { TerminalPanelProps } from '../../types/panelComponents';
 import { isHotkeyEnabledForEvent, useHotkeyStore } from '../../stores/hotkeyStore';
 import { renderLog, devLog } from '../../utils/console';
 import { getTerminalTheme } from '../../utils/terminalTheme';
-import { resolveTerminalKeyHandling } from '../../utils/terminalKeyHandling';
+import { resolveTerminalKeyHandling, shouldOpenTerminalSearch } from '../../utils/terminalKeyHandling';
 import { isMac } from '../../utils/platformUtils';
 import { FileEdit, FolderOpen } from 'lucide-react';
 import { useTerminalLinks } from '../terminal/hooks/useTerminalLinks';
@@ -27,7 +27,7 @@ import { createAtTerminalHandler } from '../../services/terminalInterceptor/hand
 import { InterceptorDropdown } from '../terminal/InterceptorDropdown';
 import { InterceptorToast } from '../terminal/InterceptorToast';
 import { usePanelStore } from '../../stores/panelStore';
-import { useConfigStore } from '../../stores/configStore';
+import { areKeyboardShortcutsEnabled, useConfigStore } from '../../stores/configStore';
 import type { InterceptorState, AtTerminalHandlerState, TerminalSuggestion } from '../../services/terminalInterceptor/types';
 import '@xterm/xterm/css/xterm.css';
 
@@ -41,7 +41,7 @@ const SKELETON_TRANSCRIPT_WIDTHS = ['w-2/3', 'w-1/2', 'w-5/6', 'w-1/3', 'w-3/4',
 // lines, and a prompt box, swept by a single shimmer so it reads as one
 // cohesive loading surface. Shown while initializing, refreshing, and CLI startup.
 const TerminalLoadingSkeleton: React.FC = () => (
-  <div className="relative w-full h-full overflow-hidden px-4 py-4 font-mono select-none" aria-label="Loading terminal">
+  <div className="relative w-full h-full overflow-hidden px-4 py-4 font-mono select-none" role="status" aria-label="Loading terminal">
     <div className="flex h-full flex-col gap-4">
       <div className="rounded-md border border-border-primary p-3 space-y-2 max-w-md">
         <div className="h-3.5 w-40 rounded bg-surface-tertiary" />
@@ -233,6 +233,8 @@ export const TerminalPanel: React.FC<TerminalPanelProps> = React.memo(({ panel,
   const interceptorRef = useRef<TerminalInterceptor | null>(null);
   const skipNextInterceptRef = useRef(false); // set by AltGr @ detection
   const terminalPowerMode = useConfigStore((state) => state.config?.terminalPowerMode ?? 'performance');
+  const keyboardShortcutsEnabled = useConfigStore((state) => areKeyboardShortcutsEnabled(state.config));
+  const keyboardShortcutsEnabledRef = useRef(keyboardShortcutsEnabled);
   const useBatterySaverTerminalVisibility = terminalPowerMode === 'batterySaver';
   const panelVisible = isActive;
   const effectiveVisible = useBatterySaverTerminalVisibility ? panelVisible && windowFocused : true;
@@ -295,6 +297,10 @@ export const TerminalPanel: React.FC<TerminalPanelProps> = React.memo(({ panel,
     isCliPanelRef.current = isCliPanel;
   }, [isCliPanel]);
 
+  useEffect(() => {
+    keyboardShortcutsEnabledRef.current = keyboardShortcutsEnabled;
+  }, [keyboardShortcutsEnabled]);
+
   useEffect(() => {
     if (terminalState?.isCliReady && !isCliReady) {
       setIsCliReady(true);
@@ -767,12 +773,11 @@ export const TerminalPanel: React.FC<TerminalPanelProps> = React.memo(({ panel,
 
   // Open search on Ctrl/Cmd+F from the container div
   const handleTerminalKeyDown = useCallback((e: React.KeyboardEvent) => {
-    const ctrlOrMeta = e.ctrlKey || e.metaKey;
-    if (ctrlOrMeta && e.key.toLowerCase() === 'f') {
+    if (shouldOpenTerminalSearch(e, keyboardShortcutsEnabled)) {
       e.preventDefault();
       openSearch();
     }
-  }, [openSearch]);
+  }, [keyboardShortcutsEnabled, openSearch]);
 
   const getDropdownPosition = useCallback((): { x: number; y: number } => {
     const container = terminalRef.current;
@@ -906,6 +911,8 @@ export const TerminalPanel: React.FC<TerminalPanelProps> = React.memo(({ panel,
 
         // Intercept app-level shortcuts before xterm consumes them
         terminal.attachCustomKeyEventHandler((e: KeyboardEvent) => {
+          if (!keyboardShortcutsEnabledRef.current) return !isHotkeyEnabledForEvent(e);
+
           const ctrlOrMeta = e.ctrlKey || e.metaKey;
 
           // Ctrl/Cmd+K: clear xterm scrollback without writing ^K to the PTY.
@@ -925,6 +932,7 @@ export const TerminalPanel: React.FC<TerminalPanelProps> = React.memo(({ panel,
             isTuiActive: tuiActiveRef.current,
             isCliPanel: isCliPanelRef.current,
             isMac: isMac(),
+            keyboardShortcutsEnabled: keyboardShortcutsEnabledRef.current,
           });
 
           // Shift+Enter sends the same ESC+CR sequence as Alt+Enter for CLI

frontend/src/components/panels/editor/FileEditor.tsx

@@ -15,7 +15,7 @@ import { ExplorerPanelState } from '../../../../../shared/types/panels';
 import { isMac, isWindows } from '../../../utils/platformUtils';
 import { formatKeyDisplay } from '../../../utils/hotkeyUtils';
 import { TerminalPopover, PopoverButton } from '../../terminal/TerminalPopover';
-import { useConfigStore } from '../../../stores/configStore';
+import { areKeyboardShortcutsEnabled, useConfigStore } from '../../../stores/configStore';
 import { LiveRegion } from '../../ui/LiveRegion';
 
 interface FileItem {
@@ -89,6 +89,7 @@ function HeadlessFileTree({
   // Platform-adaptive label
   const revealLabel = isMac() ? 'Reveal in Finder' : isWindows() ? 'Show in Explorer' : 'Show in File Manager';
   const isRemoteMode = useConfigStore((state) => state.config?.remoteDaemon?.client.mode === 'remote');
+  const keyboardShortcutsEnabled = useConfigStore((state) => areKeyboardShortcutsEnabled(state.config));
 
   // Initialize expanded state from persisted state or default to root expanded.
   // Normalize legacy '' root to ROOT_ID so saved state from the old FileTree still works.
@@ -703,7 +704,7 @@ function HeadlessFileTree({
       const isEditingText = target?.tagName === 'INPUT' || target?.tagName === 'TEXTAREA' || !!target?.isContentEditable;
       if (isEditingText && e.key !== 'Escape') return;
 
-      if ((e.metaKey || e.ctrlKey) && e.key === 'f') {
+      if (keyboardShortcutsEnabled && (e.metaKey || e.ctrlKey) && e.key === 'f') {
         e.preventDefault();
         setShowSearch(prev => !prev);
       }
@@ -722,6 +723,7 @@ function HeadlessFileTree({
           searchInputRef.current?.focus();
         }
       }
+      if (!keyboardShortcutsEnabled) return;
       if (e.key === 'F2' && selectedItems.length === 1) {
         const item = tree.getItemInstance(selectedItems[0])?.getItemData();
         if (item) {
@@ -752,7 +754,7 @@ function HeadlessFileTree({
 
     window.addEventListener('keydown', handleKeyDown);
     return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [searchQuery, showNewItemDialog, contextMenu, selectedItems, tree, startRename, handleDelete, clipboard, handlePaste]);
+  }, [searchQuery, showNewItemDialog, contextMenu, keyboardShortcutsEnabled, selectedItems, tree, startRename, handleDelete, clipboard, handlePaste]);
 
   return (
     <div

frontend/src/components/panels/logPanel/LogsView.tsx

@@ -4,6 +4,7 @@ import { cn } from '../../../utils/cn';
 import AnsiToHtml from 'ansi-to-html';
 import { useTheme } from '../../../contexts/ThemeContext';
 import { LiveRegion } from '../../ui/LiveRegion';
+import { areKeyboardShortcutsEnabled, useConfigStore } from '../../../stores/configStore';
 
 interface LogEntry {
   timestamp: string;
@@ -30,6 +31,7 @@ export const LogsView: React.FC<LogsViewProps> = ({ sessionId, isVisible }) => {
   const searchInputRef = useRef<HTMLInputElement>(null);
   const lastLogCount = useRef(0);
   const { theme } = useTheme();
+  const keyboardShortcutsEnabled = useConfigStore((state) => areKeyboardShortcutsEnabled(state.config));
 
   // Create ANSI to HTML converter with theme-aware colors
   const ansiConverter = useMemo(() => {
@@ -174,7 +176,7 @@ export const LogsView: React.FC<LogsViewProps> = ({ sessionId, isVisible }) => {
 
     const handleKeyDown = (e: KeyboardEvent) => {
       // Cmd+F or Ctrl+F for search
-      if ((e.metaKey || e.ctrlKey) && e.key === 'f') {
+      if (keyboardShortcutsEnabled && (e.metaKey || e.ctrlKey) && e.key === 'f') {
         e.preventDefault();
         setSearchVisible(true);
         setTimeout(() => searchInputRef.current?.focus(), 100);
@@ -197,7 +199,7 @@ export const LogsView: React.FC<LogsViewProps> = ({ sessionId, isVisible }) => {
 
     window.addEventListener('keydown', handleKeyDown);
     return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [isVisible, searchVisible, searchMatches, goToNextMatch, goToPreviousMatch]);
+  }, [isVisible, keyboardShortcutsEnabled, searchVisible, searchMatches, goToNextMatch, goToPreviousMatch]);
 
   const handleClearLogs = async () => {
     try {

frontend/src/components/settings/catalog.tsx

@@ -92,9 +92,9 @@ export const SETTINGS_CATEGORIES: readonly SettingsCategoryDefinition[] = [
   {
     id: 'shortcuts',
     label: 'Shortcuts',
-    description: 'Terminal snippet hotkeys.',
+    description: 'Application and terminal snippet hotkeys.',
     icon: Keyboard,
-    settingIds: ['terminal-shortcuts'],
+    settingIds: ['keyboard-shortcuts', 'command-palette-shortcut', 'terminal-shortcuts'],
     aliases: ['hotkeys', 'keyboard', 'snippets'],
   },
   {

frontend/src/components/settings/categories/ShortcutsSettings.tsx

@@ -4,16 +4,18 @@ import { Button, IconButton } from '../../ui/Button';
 import { Input, Textarea } from '../../ui/Input';
 import { SettingsSection } from '../../ui/SettingsSection';
 import { SettingRow, SettingsPage } from '../SettingRow';
+import { ImmediateToggle } from '../SettingsControls';
 import type { SettingsPersistence } from '../useSettingsPersistence';
 import type { TerminalShortcut } from '../../../types/config';
 import { formatKeyDisplay } from '../../../utils/hotkeyUtils';
 
 interface ShortcutsSettingsProps {
   persistence: SettingsPersistence;
   onDirtyChange: (dirty: boolean) => void;
+  onShowKeyboardShortcuts: () => void;
 }
 
-export function ShortcutsSettings({ persistence, onDirtyChange }: ShortcutsSettingsProps) {
+export function ShortcutsSettings({ persistence, onDirtyChange, onShowKeyboardShortcuts }: ShortcutsSettingsProps) {
   const config = persistence.config!;
   const persistedShortcuts = config.terminalShortcuts ?? [];
   const persistedKey = JSON.stringify(persistedShortcuts);
@@ -46,7 +48,40 @@ export function ShortcutsSettings({ persistence, onDirtyChange }: ShortcutsSetti
   };
 
   return (
-    <SettingsPage title="Shortcuts" description="Bind application-wide Ctrl/Cmd+Alt+letter shortcuts to terminal snippets.">
+    <SettingsPage title="Shortcuts" description="Control Pane keyboard shortcuts and terminal snippet hotkeys.">
+      <SettingsSection title="Application shortcuts">
+        <SettingRow
+          settingId="keyboard-shortcuts"
+          label="Enable Pane keyboard shortcuts"
+          description="When disabled, Pane shortcuts won't work, but native terminal and embedded app shortcuts will. The Command Palette shortcut can remain enabled below."
+          saveState={persistence.saveStates['keyboard-shortcuts']}
+        >
+          <ImmediateToggle
+            label="Enable Pane keyboard shortcuts"
+            value={config.keyboardShortcutsEnabled !== false}
+            onSave={(value) => persistence.saveConfig('keyboard-shortcuts', { keyboardShortcutsEnabled: value })}
+          />
+        </SettingRow>
+        <SettingRow
+          settingId="command-palette-shortcut"
+          label="Keep Command Palette shortcut enabled"
+          description="Keep Ctrl/Cmd+Shift+P available when other Pane keyboard shortcuts are disabled."
+          saveState={persistence.saveStates['command-palette-shortcut']}
+        >
+          <ImmediateToggle
+            label="Keep Command Palette shortcut enabled"
+            value={config.commandPaletteShortcutEnabled !== false}
+            onSave={(value) => persistence.saveConfig('command-palette-shortcut', { commandPaletteShortcutEnabled: value })}
+          />
+        </SettingRow>
+        <button
+          type="button"
+          className="text-sm font-medium text-interactive underline underline-offset-4 hover:text-interactive-hover"
+          onClick={onShowKeyboardShortcuts}
+        >
+          View all Pane keyboard shortcuts
+        </button>
+      </SettingsSection>
       <SettingsSection title="Terminal snippets">
         <SettingRow
           settingId="terminal-shortcuts"