refactor(ui): unify keybinding infrastructure and support string initialization (#21776)

packages/cli/src/ui/AppContainer.tsx

@@ -119,7 +119,7 @@ import { type InitializationResult } from '../core/initializer.js';
 import { useFocus } from './hooks/useFocus.js';
 import { useKeypress, type Key } from './hooks/useKeypress.js';
 import { KeypressPriority } from './contexts/KeypressContext.js';
-import { Command } from './keyMatchers.js';
+import { Command } from './key/keyMatchers.js';
 import { useLoadingIndicator } from './hooks/useLoadingIndicator.js';
 import { useShellInactivityStatus } from './hooks/useShellInactivityStatus.js';
 import { useFolderTrust } from './hooks/useFolderTrust.js';

packages/cli/src/ui/auth/ApiAuthDialog.tsx

@@ -13,7 +13,7 @@ import { useTextBuffer } from '../components/shared/text-buffer.js';
 import { useUIState } from '../contexts/UIStateContext.js';
 import { clearApiKey, debugLogger } from '@google/gemini-cli-core';
 import { useKeypress } from '../hooks/useKeypress.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { useKeyMatchers } from '../hooks/useKeyMatchers.js';
 
 interface ApiAuthDialogProps {

packages/cli/src/ui/components/AdminSettingsChangedDialog.tsx

@@ -8,7 +8,7 @@ import { Box, Text } from 'ink';
 import { theme } from '../semantic-colors.js';
 import { useKeypress } from '../hooks/useKeypress.js';
 import { useUIActions } from '../contexts/UIActionsContext.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { useKeyMatchers } from '../hooks/useKeyMatchers.js';
 
 export const AdminSettingsChangedDialog = () => {

packages/cli/src/ui/components/ApprovalModeIndicator.tsx

@@ -8,8 +8,8 @@ import type React from 'react';
 import { Box, Text } from 'ink';
 import { theme } from '../semantic-colors.js';
 import { ApprovalMode } from '@google/gemini-cli-core';
-import { formatCommand } from '../utils/keybindingUtils.js';
-import { Command } from '../../config/keyBindings.js';
+import { formatCommand } from '../key/keybindingUtils.js';
+import { Command } from '../key/keyBindings.js';
 
 interface ApprovalModeIndicatorProps {
   approvalMode: ApprovalMode;

packages/cli/src/ui/components/AskUserDialog.tsx

@@ -20,10 +20,10 @@ import { BaseSelectionList } from './shared/BaseSelectionList.js';
 import type { SelectionListItem } from '../hooks/useSelectionList.js';
 import { TabHeader, type Tab } from './shared/TabHeader.js';
 import { useKeypress, type Key } from '../hooks/useKeypress.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { checkExhaustive } from '@google/gemini-cli-core';
 import { TextInput } from './shared/TextInput.js';
-import { formatCommand } from '../utils/keybindingUtils.js';
+import { formatCommand } from '../key/keybindingUtils.js';
 import {
   useTextBuffer,
   expandPastePlaceholders,

packages/cli/src/ui/components/BackgroundShellDisplay.tsx

@@ -16,9 +16,9 @@ import {
 } from '@google/gemini-cli-core';
 import { cpLen, cpSlice, getCachedStringWidth } from '../utils/textUtils.js';
 import { type BackgroundShell } from '../hooks/shellCommandProcessor.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { useKeypress } from '../hooks/useKeypress.js';
-import { formatCommand } from '../utils/keybindingUtils.js';
+import { formatCommand } from '../key/keybindingUtils.js';
 import {
   ScrollableList,
   type ScrollableListRef,

packages/cli/src/ui/components/ExitPlanModeDialog.test.tsx

@@ -10,7 +10,7 @@ import { renderWithProviders } from '../../test-utils/render.js';
 import { waitFor } from '../../test-utils/async.js';
 import { ExitPlanModeDialog } from './ExitPlanModeDialog.js';
 import { useKeypress } from '../hooks/useKeypress.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import {
   ApprovalMode,
   validatePlanContent,

packages/cli/src/ui/components/ExitPlanModeDialog.tsx

@@ -22,8 +22,8 @@ import { useConfig } from '../contexts/ConfigContext.js';
 import { AskUserDialog } from './AskUserDialog.js';
 import { openFileInEditor } from '../utils/editorUtils.js';
 import { useKeypress } from '../hooks/useKeypress.js';
-import { Command } from '../keyMatchers.js';
-import { formatCommand } from '../utils/keybindingUtils.js';
+import { Command } from '../key/keyMatchers.js';
+import { formatCommand } from '../key/keybindingUtils.js';
 import { useKeyMatchers } from '../hooks/useKeyMatchers.js';
 
 export interface ExitPlanModeDialogProps {

packages/cli/src/ui/components/FooterConfigDialog.tsx

@@ -11,7 +11,7 @@ import { theme } from '../semantic-colors.js';
 import { useSettingsStore } from '../contexts/SettingsContext.js';
 import { useUIState } from '../contexts/UIStateContext.js';
 import { useKeypress, type Key } from '../hooks/useKeypress.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { FooterRow, type FooterRowItem } from './Footer.js';
 import { ALL_ITEMS, resolveFooterState } from '../../config/footerItems.js';
 import { SettingScope } from '../../config/settings.js';

packages/cli/src/ui/components/Help.tsx

@@ -10,8 +10,8 @@ import { theme } from '../semantic-colors.js';
 import { type SlashCommand, CommandKind } from '../commands/types.js';
 import { KEYBOARD_SHORTCUTS_URL } from '../constants.js';
 import { sanitizeForDisplay } from '../utils/textUtils.js';
-import { formatCommand } from '../utils/keybindingUtils.js';
-import { Command } from '../../config/keyBindings.js';
+import { formatCommand } from '../key/keybindingUtils.js';
+import { Command } from '../key/keyBindings.js';
 
 interface Help {
   commands: readonly SlashCommand[];

packages/cli/src/ui/components/HooksDialog.tsx

@@ -9,7 +9,7 @@ import { useState, useMemo } from 'react';
 import { Box, Text } from 'ink';
 import { theme } from '../semantic-colors.js';
 import { useKeypress } from '../hooks/useKeypress.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { useKeyMatchers } from '../hooks/useKeyMatchers.js';
 
 /**

packages/cli/src/ui/components/InputPrompt.test.tsx

@@ -44,7 +44,7 @@ import { terminalCapabilityManager } from '../utils/terminalCapabilityManager.js
 import type { UIState } from '../contexts/UIStateContext.js';
 import { isLowColorDepth } from '../utils/terminalUtils.js';
 import { cpLen } from '../utils/textUtils.js';
-import { defaultKeyMatchers, Command } from '../keyMatchers.js';
+import { defaultKeyMatchers, Command } from '../key/keyMatchers.js';
 import type { Key } from '../hooks/useKeypress.js';
 import {
   appEvents,

packages/cli/src/ui/components/InputPrompt.tsx

@@ -36,8 +36,8 @@ import {
 } from '../hooks/useCommandCompletion.js';
 import type { Key } from '../hooks/useKeypress.js';
 import { useKeypress } from '../hooks/useKeypress.js';
-import { Command } from '../keyMatchers.js';
-import { formatCommand } from '../utils/keybindingUtils.js';
+import { Command } from '../key/keyMatchers.js';
+import { formatCommand } from '../key/keybindingUtils.js';
 import type { CommandContext, SlashCommand } from '../commands/types.js';
 import type { Config } from '@google/gemini-cli-core';
 import { ApprovalMode, coreEvents, debugLogger } from '@google/gemini-cli-core';

packages/cli/src/ui/components/PolicyUpdateDialog.tsx

@@ -16,7 +16,7 @@ import { theme } from '../semantic-colors.js';
 import type { RadioSelectItem } from './shared/RadioButtonSelect.js';
 import { RadioButtonSelect } from './shared/RadioButtonSelect.js';
 import { useKeypress } from '../hooks/useKeypress.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { useKeyMatchers } from '../hooks/useKeyMatchers.js';
 
 export enum PolicyUpdateChoice {

packages/cli/src/ui/components/RawMarkdownIndicator.tsx

@@ -7,8 +7,8 @@
 import type React from 'react';
 import { Box, Text } from 'ink';
 import { theme } from '../semantic-colors.js';
-import { formatCommand } from '../utils/keybindingUtils.js';
-import { Command } from '../../config/keyBindings.js';
+import { formatCommand } from '../key/keybindingUtils.js';
+import { Command } from '../key/keyBindings.js';
 
 export const RawMarkdownIndicator: React.FC = () => {
   const modKey = formatCommand(Command.TOGGLE_MARKDOWN);

packages/cli/src/ui/components/RewindConfirmation.tsx

@@ -13,7 +13,7 @@ import type { RadioSelectItem } from './shared/RadioButtonSelect.js';
 import type { FileChangeStats } from '../utils/rewindFileOps.js';
 import { useKeypress } from '../hooks/useKeypress.js';
 import { formatTimeAgo } from '../utils/formatters.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { useKeyMatchers } from '../hooks/useKeyMatchers.js';
 
 export enum RewindOutcome {

packages/cli/src/ui/components/RewindViewer.tsx

@@ -19,7 +19,7 @@ import { useKeypress } from '../hooks/useKeypress.js';
 import { useRewind } from '../hooks/useRewind.js';
 import { RewindConfirmation, RewindOutcome } from './RewindConfirmation.js';
 import { stripReferenceContent } from '../utils/formatters.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { CliSpinner } from './CliSpinner.js';
 import { ExpandableText } from './shared/ExpandableText.js';
 import { useKeyMatchers } from '../hooks/useKeyMatchers.js';

packages/cli/src/ui/components/ShellInputPrompt.tsx

@@ -8,9 +8,9 @@ import { useCallback } from 'react';
 import type React from 'react';
 import { useKeypress } from '../hooks/useKeypress.js';
 import { ShellExecutionService } from '@google/gemini-cli-core';
-import { keyToAnsi, type Key } from '../hooks/keyToAnsi.js';
+import { keyToAnsi, type Key } from '../key/keyToAnsi.js';
 import { ACTIVE_SHELL_MAX_LINES } from '../constants.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { useKeyMatchers } from '../hooks/useKeyMatchers.js';
 
 export interface ShellInputPromptProps {

packages/cli/src/ui/components/ShortcutsHelp.tsx

@@ -10,8 +10,8 @@ import { theme } from '../semantic-colors.js';
 import { isNarrowWidth } from '../utils/isNarrowWidth.js';
 import { SectionHeader } from './shared/SectionHeader.js';
 import { useUIState } from '../contexts/UIStateContext.js';
-import { Command } from '../../config/keyBindings.js';
-import { formatCommand } from '../utils/keybindingUtils.js';
+import { Command } from '../key/keyBindings.js';
+import { formatCommand } from '../key/keybindingUtils.js';
 
 type ShortcutItem = {
   key: string;
@@ -21,7 +21,7 @@ type ShortcutItem = {
 const buildShortcutItems = (): ShortcutItem[] => [
   { key: '!', description: 'shell mode' },
   { key: '@', description: 'select file or folder' },
-  { key: formatCommand(Command.REWIND), description: 'clear & rewind' },
+  { key: 'Double Esc', description: 'clear & rewind' },
   { key: formatCommand(Command.FOCUS_SHELL_INPUT), description: 'focus UI' },
   { key: formatCommand(Command.TOGGLE_YOLO), description: 'YOLO mode' },
   {

packages/cli/src/ui/components/ValidationDialog.tsx

@@ -16,7 +16,7 @@ import {
   type ValidationIntent,
 } from '@google/gemini-cli-core';
 import { useKeypress } from '../hooks/useKeypress.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { useKeyMatchers } from '../hooks/useKeyMatchers.js';
 
 interface ValidationDialogProps {

packages/cli/src/ui/components/messages/Todo.tsx

@@ -11,8 +11,8 @@ import { useMemo } from 'react';
 import type { HistoryItemToolGroup } from '../../types.js';
 import { Checklist } from '../Checklist.js';
 import type { ChecklistItemData } from '../ChecklistItem.js';
-import { formatCommand } from '../../utils/keybindingUtils.js';
-import { Command } from '../../../config/keyBindings.js';
+import { formatCommand } from '../../key/keybindingUtils.js';
+import { Command } from '../../key/keyBindings.js';
 
 export const TodoTray: React.FC = () => {
   const uiState = useUIState();

packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx

@@ -29,8 +29,8 @@ import {
 import { useKeypress } from '../../hooks/useKeypress.js';
 import { theme } from '../../semantic-colors.js';
 import { useSettings } from '../../contexts/SettingsContext.js';
-import { Command } from '../../keyMatchers.js';
-import { formatCommand } from '../../utils/keybindingUtils.js';
+import { Command } from '../../key/keyMatchers.js';
+import { formatCommand } from '../../key/keybindingUtils.js';
 import { AskUserDialog } from '../AskUserDialog.js';
 import { ExitPlanModeDialog } from '../ExitPlanModeDialog.js';
 import { WarningMessage } from './WarningMessage.js';

packages/cli/src/ui/components/messages/ToolShared.tsx

@@ -23,8 +23,8 @@ import {
   CoreToolCallStatus,
 } from '@google/gemini-cli-core';
 import { useInactivityTimer } from '../../hooks/useInactivityTimer.js';
-import { formatCommand } from '../../utils/keybindingUtils.js';
-import { Command } from '../../../config/keyBindings.js';
+import { formatCommand } from '../../key/keybindingUtils.js';
+import { Command } from '../../key/keyBindings.js';
 
 export const STATUS_INDICATOR_WIDTH = 3;
 

packages/cli/src/ui/components/shared/BaseSettingsDialog.tsx

@@ -19,10 +19,10 @@ import { TextInput } from './TextInput.js';
 import type { TextBuffer } from './text-buffer.js';
 import { cpSlice, cpLen, cpIndexToOffset } from '../../utils/textUtils.js';
 import { useKeypress, type Key } from '../../hooks/useKeypress.js';
-import { Command } from '../../keyMatchers.js';
+import { Command } from '../../key/keyMatchers.js';
 import { useSettingsNavigation } from '../../hooks/useSettingsNavigation.js';
 import { useInlineEditBuffer } from '../../hooks/useInlineEditBuffer.js';
-import { formatCommand } from '../../utils/keybindingUtils.js';
+import { formatCommand } from '../../key/keybindingUtils.js';
 import { useKeyMatchers } from '../../hooks/useKeyMatchers.js';
 
 /**

packages/cli/src/ui/components/shared/MaxSizedBox.tsx

@@ -10,8 +10,8 @@ import { Box, Text, ResizeObserver, type DOMElement } from 'ink';
 import { theme } from '../../semantic-colors.js';
 import { useOverflowActions } from '../../contexts/OverflowContext.js';
 import { isNarrowWidth } from '../../utils/isNarrowWidth.js';
-import { Command } from '../../../config/keyBindings.js';
-import { formatCommand } from '../../utils/keybindingUtils.js';
+import { Command } from '../../key/keyBindings.js';
+import { formatCommand } from '../../key/keybindingUtils.js';
 
 /**
  * Minimum height for the MaxSizedBox component.

packages/cli/src/ui/components/shared/Scrollable.tsx

@@ -19,7 +19,7 @@ import { useKeypress, type Key } from '../../hooks/useKeypress.js';
 import { useScrollable } from '../../contexts/ScrollProvider.js';
 import { useAnimatedScrollbar } from '../../hooks/useAnimatedScrollbar.js';
 import { useBatchedScroll } from '../../hooks/useBatchedScroll.js';
-import { Command } from '../../keyMatchers.js';
+import { Command } from '../../key/keyMatchers.js';
 import { useOverflowActions } from '../../contexts/OverflowContext.js';
 import { useKeyMatchers } from '../../hooks/useKeyMatchers.js';
 

packages/cli/src/ui/components/shared/ScrollableList.tsx

@@ -22,7 +22,7 @@ import { useScrollable } from '../../contexts/ScrollProvider.js';
 import { Box, type DOMElement } from 'ink';
 import { useAnimatedScrollbar } from '../../hooks/useAnimatedScrollbar.js';
 import { useKeypress, type Key } from '../../hooks/useKeypress.js';
-import { Command } from '../../keyMatchers.js';
+import { Command } from '../../key/keyMatchers.js';
 import { useKeyMatchers } from '../../hooks/useKeyMatchers.js';
 
 const ANIMATION_FRAME_DURATION_MS = 33;

packages/cli/src/ui/components/shared/SearchableList.tsx

@@ -11,7 +11,7 @@ import { useSelectionList } from '../../hooks/useSelectionList.js';
 import { TextInput } from './TextInput.js';
 import type { TextBuffer } from './text-buffer.js';
 import { useKeypress } from '../../hooks/useKeypress.js';
-import { Command } from '../../keyMatchers.js';
+import { Command } from '../../key/keyMatchers.js';
 import { useKeyMatchers } from '../../hooks/useKeyMatchers.js';
 
 /**

packages/cli/src/ui/components/shared/TextInput.tsx

@@ -14,7 +14,7 @@ import { theme } from '../../semantic-colors.js';
 import type { TextBuffer } from './text-buffer.js';
 import { expandPastePlaceholders } from './text-buffer.js';
 import { cpSlice, cpIndexToOffset } from '../../utils/textUtils.js';
-import { Command } from '../../keyMatchers.js';
+import { Command } from '../../key/keyMatchers.js';
 import { useKeyMatchers } from '../../hooks/useKeyMatchers.js';
 
 export interface TextInputProps {

packages/cli/src/ui/components/shared/text-buffer.ts

@@ -25,7 +25,7 @@ import {
 } from '../../utils/textUtils.js';
 import { parsePastedPaths } from '../../utils/clipboardUtils.js';
 import type { Key } from '../../contexts/KeypressContext.js';
-import { Command } from '../../keyMatchers.js';
+import { Command } from '../../key/keyMatchers.js';
 import type { VimAction } from './vim-buffer-actions.js';
 import { handleVimAction } from './vim-buffer-actions.js';
 import { LRU_BUFFER_PERF_CACHE_LIMIT } from '../../constants.js';

packages/cli/src/ui/components/triage/TriageDuplicates.tsx

@@ -10,7 +10,7 @@ import Spinner from 'ink-spinner';
 import type { Config } from '@google/gemini-cli-core';
 import { debugLogger, spawnAsync, LlmRole } from '@google/gemini-cli-core';
 import { useKeypress } from '../../hooks/useKeypress.js';
-import { Command } from '../../keyMatchers.js';
+import { Command } from '../../key/keyMatchers.js';
 import { useKeyMatchers } from '../../hooks/useKeyMatchers.js';
 
 interface Issue {

packages/cli/src/ui/components/triage/TriageIssues.tsx

@@ -10,7 +10,7 @@ import Spinner from 'ink-spinner';
 import type { Config } from '@google/gemini-cli-core';
 import { debugLogger, spawnAsync, LlmRole } from '@google/gemini-cli-core';
 import { useKeypress } from '../../hooks/useKeypress.js';
-import { Command } from '../../keyMatchers.js';
+import { Command } from '../../key/keyMatchers.js';
 import { TextInput } from '../shared/TextInput.js';
 import { useTextBuffer } from '../shared/text-buffer.js';
 import { useKeyMatchers } from '../../hooks/useKeyMatchers.js';

packages/cli/src/ui/hooks/keyToAnsi.ts

@@ -1,77 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import type { Key } from '../contexts/KeypressContext.js';
-
-export type { Key };
-
-/**
- * Translates a Key object into its corresponding ANSI escape sequence.
- * This is useful for sending control characters to a pseudo-terminal.
- *
- * @param key The Key object to translate.
- * @returns The ANSI escape sequence as a string, or null if no mapping exists.
- */
-export function keyToAnsi(key: Key): string | null {
-  if (key.ctrl) {
-    // Ctrl + letter
-    if (key.name >= 'a' && key.name <= 'z') {
-      return String.fromCharCode(
-        key.name.charCodeAt(0) - 'a'.charCodeAt(0) + 1,
-      );
-    }
-    // Other Ctrl combinations might need specific handling
-    switch (key.name) {
-      case 'c':
-        return '\x03'; // ETX (End of Text), commonly used for interrupt
-      // Add other special ctrl cases if needed
-      default:
-        break;
-    }
-  }
-
-  // Arrow keys and other special keys
-  switch (key.name) {
-    case 'up':
-      return '\x1b[A';
-    case 'down':
-      return '\x1b[B';
-    case 'right':
-      return '\x1b[C';
-    case 'left':
-      return '\x1b[D';
-    case 'escape':
-      return '\x1b';
-    case 'tab':
-      return '\t';
-    case 'backspace':
-      return '\x7f';
-    case 'delete':
-      return '\x1b[3~';
-    case 'home':
-      return '\x1b[H';
-    case 'end':
-      return '\x1b[F';
-    case 'pageup':
-      return '\x1b[5~';
-    case 'pagedown':
-      return '\x1b[6~';
-    default:
-      break;
-  }
-
-  // Enter/Return
-  if (key.name === 'return') {
-    return '\r';
-  }
-
-  // If it's a simple character, return it.
-  if (!key.ctrl && !key.cmd && key.sequence) {
-    return key.sequence;
-  }
-
-  return null;
-}

packages/cli/src/ui/hooks/useApprovalModeIndicator.ts

@@ -11,7 +11,7 @@ import {
   getAdminErrorMessage,
 } from '@google/gemini-cli-core';
 import { useKeypress } from './useKeypress.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { useKeyMatchers } from './useKeyMatchers.js';
 import type { HistoryItemWithoutId } from '../types.js';
 import { MessageType } from '../types.js';

packages/cli/src/ui/hooks/useKeyMatchers.ts

@@ -5,8 +5,8 @@
  */
 
 import { useMemo } from 'react';
-import type { KeyMatchers } from '../keyMatchers.js';
-import { defaultKeyMatchers } from '../keyMatchers.js';
+import type { KeyMatchers } from '../key/keyMatchers.js';
+import { defaultKeyMatchers } from '../key/keyMatchers.js';
 
 /**
  * Hook to retrieve the currently active key matchers.

packages/cli/src/ui/hooks/useSelectionList.ts

@@ -6,7 +6,7 @@
 
 import { useReducer, useRef, useEffect, useCallback } from 'react';
 import { useKeypress, type Key } from './useKeypress.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { debugLogger } from '@google/gemini-cli-core';
 import { useKeyMatchers } from './useKeyMatchers.js';
 

packages/cli/src/ui/hooks/useSuspend.test.ts

@@ -29,8 +29,8 @@ import {
   cleanupTerminalOnExit,
   terminalCapabilityManager,
 } from '../utils/terminalCapabilityManager.js';
-import { formatCommand } from '../utils/keybindingUtils.js';
-import { Command } from '../../config/keyBindings.js';
+import { formatCommand } from '../key/keybindingUtils.js';
+import { Command } from '../key/keyBindings.js';
 
 vi.mock('@google/gemini-cli-core', async () => {
   const actual = await vi.importActual('@google/gemini-cli-core');

packages/cli/src/ui/hooks/useSuspend.ts

@@ -20,8 +20,8 @@ import {
   terminalCapabilityManager,
 } from '../utils/terminalCapabilityManager.js';
 import { WARNING_PROMPT_DURATION_MS } from '../constants.js';
-import { formatCommand } from '../utils/keybindingUtils.js';
-import { Command } from '../../config/keyBindings.js';
+import { formatCommand } from '../key/keybindingUtils.js';
+import { Command } from '../key/keyBindings.js';
 
 interface UseSuspendProps {
   handleWarning: (message: string) => void;

packages/cli/src/ui/hooks/useTabbedNavigation.test.ts

@@ -9,18 +9,12 @@ import { act } from 'react';
 import { renderHook } from '../../test-utils/render.js';
 import { useTabbedNavigation } from './useTabbedNavigation.js';
 import { useKeypress } from './useKeypress.js';
-import { useKeyMatchers } from './useKeyMatchers.js';
-import type { KeyMatchers } from '../keyMatchers.js';
 import type { Key, KeypressHandler } from '../contexts/KeypressContext.js';
 
 vi.mock('./useKeypress.js', () => ({
   useKeypress: vi.fn(),
 }));
 
-vi.mock('./useKeyMatchers.js', () => ({
-  useKeyMatchers: vi.fn(),
-}));
-
 const createKey = (partial: Partial<Key>): Key => ({
   name: partial.name || '',
   sequence: partial.sequence || '',
@@ -32,27 +26,10 @@ const createKey = (partial: Partial<Key>): Key => ({
   ...partial,
 });
 
-const mockKeyMatchers = {
-  'cursor.left': vi.fn((key) => key.name === 'left'),
-  'cursor.right': vi.fn((key) => key.name === 'right'),
-  'dialog.next': vi.fn((key) => key.name === 'tab' && !key.shift),
-  'dialog.previous': vi.fn((key) => key.name === 'tab' && key.shift),
-} as unknown as KeyMatchers;
-
-vi.mock('../keyMatchers.js', () => ({
-  Command: {
-    MOVE_LEFT: 'cursor.left',
-    MOVE_RIGHT: 'cursor.right',
-    DIALOG_NEXT: 'dialog.next',
-    DIALOG_PREV: 'dialog.previous',
-  },
-}));
-
 describe('useTabbedNavigation', () => {
   let capturedHandler: KeypressHandler;
 
   beforeEach(() => {
-    vi.mocked(useKeyMatchers).mockReturnValue(mockKeyMatchers);
     vi.mocked(useKeypress).mockImplementation((handler) => {
       capturedHandler = handler;
     });

packages/cli/src/ui/hooks/useTabbedNavigation.ts

@@ -6,7 +6,7 @@
 
 import { useReducer, useCallback, useEffect, useRef } from 'react';
 import { useKeypress, type Key } from './useKeypress.js';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { useKeyMatchers } from './useKeyMatchers.js';
 
 /**

packages/cli/src/ui/hooks/vim.ts

@@ -9,7 +9,7 @@ import type { Key } from './useKeypress.js';
 import type { TextBuffer } from '../components/shared/text-buffer.js';
 import { useVimMode } from '../contexts/VimModeContext.js';
 import { debugLogger } from '@google/gemini-cli-core';
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import { useKeyMatchers } from './useKeyMatchers.js';
 
 export type VimMode = 'NORMAL' | 'INSERT';

packages/cli/src/ui/key/keyBindings.test.ts

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { KeyBindingConfig } from './keyBindings.js';
+import {
+  Command,
+  commandCategories,
+  commandDescriptions,
+  defaultKeyBindings,
+  KeyBinding,
+} from './keyBindings.js';
+
+describe('KeyBinding', () => {
+  describe('constructor', () => {
+    it('should parse a simple key', () => {
+      const binding = new KeyBinding('a');
+      expect(binding.key).toBe('a');
+      expect(binding.ctrl).toBe(false);
+      expect(binding.shift).toBe(false);
+      expect(binding.alt).toBe(false);
+      expect(binding.cmd).toBe(false);
+    });
+
+    it('should parse ctrl+key', () => {
+      const binding = new KeyBinding('ctrl+c');
+      expect(binding.key).toBe('c');
+      expect(binding.ctrl).toBe(true);
+    });
+
+    it('should parse shift+key', () => {
+      const binding = new KeyBinding('shift+z');
+      expect(binding.key).toBe('z');
+      expect(binding.shift).toBe(true);
+    });
+
+    it('should parse alt+key', () => {
+      const binding = new KeyBinding('alt+left');
+      expect(binding.key).toBe('left');
+      expect(binding.alt).toBe(true);
+    });
+
+    it('should parse cmd+key', () => {
+      const binding = new KeyBinding('cmd+f');
+      expect(binding.key).toBe('f');
+      expect(binding.cmd).toBe(true);
+    });
+
+    it('should handle aliases (option/opt/meta)', () => {
+      const optionBinding = new KeyBinding('option+b');
+      expect(optionBinding.key).toBe('b');
+      expect(optionBinding.alt).toBe(true);
+
+      const optBinding = new KeyBinding('opt+b');
+      expect(optBinding.key).toBe('b');
+      expect(optBinding.alt).toBe(true);
+
+      const metaBinding = new KeyBinding('meta+enter');
+      expect(metaBinding.key).toBe('enter');
+      expect(metaBinding.cmd).toBe(true);
+    });
+
+    it('should parse multiple modifiers', () => {
+      const binding = new KeyBinding('ctrl+shift+alt+cmd+x');
+      expect(binding.key).toBe('x');
+      expect(binding.ctrl).toBe(true);
+      expect(binding.shift).toBe(true);
+      expect(binding.alt).toBe(true);
+      expect(binding.cmd).toBe(true);
+    });
+
+    it('should be case-insensitive', () => {
+      const binding = new KeyBinding('CTRL+Shift+F');
+      expect(binding.key).toBe('f');
+      expect(binding.ctrl).toBe(true);
+      expect(binding.shift).toBe(true);
+    });
+
+    it('should handle named keys with modifiers', () => {
+      const binding = new KeyBinding('ctrl+return');
+      expect(binding.key).toBe('return');
+      expect(binding.ctrl).toBe(true);
+    });
+
+    it('should throw an error for invalid keys or typos in modifiers', () => {
+      expect(() => new KeyBinding('ctrl+unknown')).toThrow(
+        'Invalid keybinding key: "unknown" in "ctrl+unknown"',
+      );
+      expect(() => new KeyBinding('ctlr+a')).toThrow(
+        'Invalid keybinding key: "ctlr+a" in "ctlr+a"',
+      );
+    });
+
+    it('should throw an error for literal "+" as key (must use "=")', () => {
+      // VS Code style peeling logic results in "+" as the remains
+      expect(() => new KeyBinding('alt++')).toThrow(
+        'Invalid keybinding key: "+" in "alt++"',
+      );
+    });
+  });
+});
+
+describe('keyBindings config', () => {
+  describe('defaultKeyBindings', () => {
+    it('should have bindings for all commands', () => {
+      const commands = Object.values(Command);
+
+      for (const command of commands) {
+        expect(defaultKeyBindings[command]).toBeDefined();
+        expect(Array.isArray(defaultKeyBindings[command])).toBe(true);
+        expect(defaultKeyBindings[command]?.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('should export all required types', () => {
+      // Basic type checks
+      expect(typeof Command.HOME).toBe('string');
+      expect(typeof Command.END).toBe('string');
+
+      // Config should be readonly
+      const config: KeyBindingConfig = defaultKeyBindings;
+      expect(config[Command.HOME]).toBeDefined();
+    });
+  });
+
+  describe('command metadata', () => {
+    const commandValues = Object.values(Command);
+
+    it('has a description entry for every command', () => {
+      const describedCommands = Object.keys(commandDescriptions);
+      expect(describedCommands.sort()).toEqual([...commandValues].sort());
+
+      for (const command of commandValues) {
+        expect(typeof commandDescriptions[command]).toBe('string');
+        expect(commandDescriptions[command]?.trim()).not.toHaveLength(0);
+      }
+    });
+
+    it('categorizes each command exactly once', () => {
+      const seen = new Set<Command>();
+
+      for (const category of commandCategories) {
+        expect(typeof category.title).toBe('string');
+        expect(Array.isArray(category.commands)).toBe(true);
+
+        for (const command of category.commands) {
+          expect(commandValues).toContain(command);
+          expect(seen.has(command)).toBe(false);
+          seen.add(command);
+        }
+      }
+
+      expect(seen.size).toBe(commandValues.length);
+    });
+  });
+});

packages/cli/src/ui/key/keyBindings.ts

@@ -0,0 +1,604 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Command enum for all available keyboard shortcuts
+ */
+import type { Key } from '../hooks/useKeypress.js';
+
+export enum Command {
+  // Basic Controls
+  RETURN = 'basic.confirm',
+  ESCAPE = 'basic.cancel',
+  QUIT = 'basic.quit',
+  EXIT = 'basic.exit',
+
+  // Cursor Movement
+  HOME = 'cursor.home',
+  END = 'cursor.end',
+  MOVE_UP = 'cursor.up',
+  MOVE_DOWN = 'cursor.down',
+  MOVE_LEFT = 'cursor.left',
+  MOVE_RIGHT = 'cursor.right',
+  MOVE_WORD_LEFT = 'cursor.wordLeft',
+  MOVE_WORD_RIGHT = 'cursor.wordRight',
+
+  // Editing
+  KILL_LINE_RIGHT = 'edit.deleteRightAll',
+  KILL_LINE_LEFT = 'edit.deleteLeftAll',
+  CLEAR_INPUT = 'edit.clear',
+  DELETE_WORD_BACKWARD = 'edit.deleteWordLeft',
+  DELETE_WORD_FORWARD = 'edit.deleteWordRight',
+  DELETE_CHAR_LEFT = 'edit.deleteLeft',
+  DELETE_CHAR_RIGHT = 'edit.deleteRight',
+  UNDO = 'edit.undo',
+  REDO = 'edit.redo',
+
+  // Scrolling
+  SCROLL_UP = 'scroll.up',
+  SCROLL_DOWN = 'scroll.down',
+  SCROLL_HOME = 'scroll.home',
+  SCROLL_END = 'scroll.end',
+  PAGE_UP = 'scroll.pageUp',
+  PAGE_DOWN = 'scroll.pageDown',
+
+  // History & Search
+  HISTORY_UP = 'history.previous',
+  HISTORY_DOWN = 'history.next',
+  REVERSE_SEARCH = 'history.search.start',
+  SUBMIT_REVERSE_SEARCH = 'history.search.submit',
+  ACCEPT_SUGGESTION_REVERSE_SEARCH = 'history.search.accept',
+
+  // Navigation
+  NAVIGATION_UP = 'nav.up',
+  NAVIGATION_DOWN = 'nav.down',
+  DIALOG_NAVIGATION_UP = 'nav.dialog.up',
+  DIALOG_NAVIGATION_DOWN = 'nav.dialog.down',
+  DIALOG_NEXT = 'nav.dialog.next',
+  DIALOG_PREV = 'nav.dialog.previous',
+
+  // Suggestions & Completions
+  ACCEPT_SUGGESTION = 'suggest.accept',
+  COMPLETION_UP = 'suggest.focusPrevious',
+  COMPLETION_DOWN = 'suggest.focusNext',
+  EXPAND_SUGGESTION = 'suggest.expand',
+  COLLAPSE_SUGGESTION = 'suggest.collapse',
+
+  // Text Input
+  SUBMIT = 'input.submit',
+  NEWLINE = 'input.newline',
+  OPEN_EXTERNAL_EDITOR = 'input.openExternalEditor',
+  PASTE_CLIPBOARD = 'input.paste',
+
+  BACKGROUND_SHELL_ESCAPE = 'backgroundShellEscape',
+  BACKGROUND_SHELL_SELECT = 'backgroundShellSelect',
+  TOGGLE_BACKGROUND_SHELL = 'toggleBackgroundShell',
+  TOGGLE_BACKGROUND_SHELL_LIST = 'toggleBackgroundShellList',
+  KILL_BACKGROUND_SHELL = 'backgroundShell.kill',
+  UNFOCUS_BACKGROUND_SHELL = 'backgroundShell.unfocus',
+  UNFOCUS_BACKGROUND_SHELL_LIST = 'backgroundShell.listUnfocus',
+  SHOW_BACKGROUND_SHELL_UNFOCUS_WARNING = 'backgroundShell.unfocusWarning',
+  SHOW_SHELL_INPUT_UNFOCUS_WARNING = 'shellInput.unfocusWarning',
+
+  // App Controls
+  SHOW_ERROR_DETAILS = 'app.showErrorDetails',
+  SHOW_FULL_TODOS = 'app.showFullTodos',
+  SHOW_IDE_CONTEXT_DETAIL = 'app.showIdeContextDetail',
+  TOGGLE_MARKDOWN = 'app.toggleMarkdown',
+  TOGGLE_COPY_MODE = 'app.toggleCopyMode',
+  TOGGLE_YOLO = 'app.toggleYolo',
+  CYCLE_APPROVAL_MODE = 'app.cycleApprovalMode',
+  SHOW_MORE_LINES = 'app.showMoreLines',
+  EXPAND_PASTE = 'app.expandPaste',
+  FOCUS_SHELL_INPUT = 'app.focusShellInput',
+  UNFOCUS_SHELL_INPUT = 'app.unfocusShellInput',
+  CLEAR_SCREEN = 'app.clearScreen',
+  RESTART_APP = 'app.restart',
+  SUSPEND_APP = 'app.suspend',
+}
+
+/**
+ * Data-driven key binding structure for user configuration
+ */
+export class KeyBinding {
+  private static readonly VALID_KEYS = new Set([
+    // Letters & Numbers
+    ...'abcdefghijklmnopqrstuvwxyz0123456789',
+    // Punctuation
+    '`',
+    '-',
+    '=',
+    '[',
+    ']',
+    '\\',
+    ';',
+    "'",
+    ',',
+    '.',
+    '/',
+    // Navigation & Actions
+    'left',
+    'up',
+    'right',
+    'down',
+    'pageup',
+    'pagedown',
+    'end',
+    'home',
+    'tab',
+    'enter',
+    'escape',
+    'space',
+    'backspace',
+    'delete',
+    'pausebreak',
+    'capslock',
+    'insert',
+    'numlock',
+    'scrolllock',
+    // Function Keys
+    ...Array.from({ length: 19 }, (_, i) => `f${i + 1}`),
+    // Numpad
+    ...Array.from({ length: 10 }, (_, i) => `numpad${i}`),
+    'numpad_multiply',
+    'numpad_add',
+    'numpad_separator',
+    'numpad_subtract',
+    'numpad_decimal',
+    'numpad_divide',
+    // Gemini CLI legacy/internal support
+    'return',
+  ]);
+
+  /** The key name (e.g., 'a', 'return', 'tab', 'escape') */
+  readonly key: string;
+  readonly shift: boolean;
+  readonly alt: boolean;
+  readonly ctrl: boolean;
+  readonly cmd: boolean;
+
+  constructor(pattern: string) {
+    let remains = pattern.toLowerCase().trim();
+    let shift = false;
+    let alt = false;
+    let ctrl = false;
+    let cmd = false;
+
+    let matched: boolean;
+    do {
+      matched = false;
+      if (remains.startsWith('ctrl+')) {
+        ctrl = true;
+        remains = remains.slice(5);
+        matched = true;
+      } else if (remains.startsWith('shift+')) {
+        shift = true;
+        remains = remains.slice(6);
+        matched = true;
+      } else if (remains.startsWith('alt+')) {
+        alt = true;
+        remains = remains.slice(4);
+        matched = true;
+      } else if (remains.startsWith('option+')) {
+        alt = true;
+        remains = remains.slice(7);
+        matched = true;
+      } else if (remains.startsWith('opt+')) {
+        alt = true;
+        remains = remains.slice(4);
+        matched = true;
+      } else if (remains.startsWith('cmd+')) {
+        cmd = true;
+        remains = remains.slice(4);
+        matched = true;
+      } else if (remains.startsWith('meta+')) {
+        cmd = true;
+        remains = remains.slice(5);
+        matched = true;
+      }
+    } while (matched);
+
+    const key = remains;
+
+    if (!KeyBinding.VALID_KEYS.has(key)) {
+      throw new Error(`Invalid keybinding key: "${key}" in "${pattern}"`);
+    }
+
+    this.key = key;
+    this.shift = shift;
+    this.alt = alt;
+    this.ctrl = ctrl;
+    this.cmd = cmd;
+  }
+
+  matches(key: Key): boolean {
+    return (
+      this.key === key.name &&
+      !!key.shift === !!this.shift &&
+      !!key.alt === !!this.alt &&
+      !!key.ctrl === !!this.ctrl &&
+      !!key.cmd === !!this.cmd
+    );
+  }
+}
+
+/**
+ * Configuration type mapping commands to their key bindings
+ */
+export type KeyBindingConfig = {
+  readonly [C in Command]: readonly KeyBinding[];
+};
+
+/**
+ * Default key binding configuration
+ * Matches the original hard-coded logic exactly
+ */
+export const defaultKeyBindings: KeyBindingConfig = {
+  // Basic Controls
+  [Command.RETURN]: [new KeyBinding('return')],
+  [Command.ESCAPE]: [new KeyBinding('escape'), new KeyBinding('ctrl+[')],
+  [Command.QUIT]: [new KeyBinding('ctrl+c')],
+  [Command.EXIT]: [new KeyBinding('ctrl+d')],
+
+  // Cursor Movement
+  [Command.HOME]: [new KeyBinding('ctrl+a'), new KeyBinding('home')],
+  [Command.END]: [new KeyBinding('ctrl+e'), new KeyBinding('end')],
+  [Command.MOVE_UP]: [new KeyBinding('up')],
+  [Command.MOVE_DOWN]: [new KeyBinding('down')],
+  [Command.MOVE_LEFT]: [new KeyBinding('left')],
+  [Command.MOVE_RIGHT]: [new KeyBinding('right'), new KeyBinding('ctrl+f')],
+  [Command.MOVE_WORD_LEFT]: [
+    new KeyBinding('ctrl+left'),
+    new KeyBinding('alt+left'),
+    new KeyBinding('alt+b'),
+  ],
+  [Command.MOVE_WORD_RIGHT]: [
+    new KeyBinding('ctrl+right'),
+    new KeyBinding('alt+right'),
+    new KeyBinding('alt+f'),
+  ],
+
+  // Editing
+  [Command.KILL_LINE_RIGHT]: [new KeyBinding('ctrl+k')],
+  [Command.KILL_LINE_LEFT]: [new KeyBinding('ctrl+u')],
+  [Command.CLEAR_INPUT]: [new KeyBinding('ctrl+c')],
+  [Command.DELETE_WORD_BACKWARD]: [
+    new KeyBinding('ctrl+backspace'),
+    new KeyBinding('alt+backspace'),
+    new KeyBinding('ctrl+w'),
+  ],
+  [Command.DELETE_WORD_FORWARD]: [
+    new KeyBinding('ctrl+delete'),
+    new KeyBinding('alt+delete'),
+    new KeyBinding('alt+d'),
+  ],
+  [Command.DELETE_CHAR_LEFT]: [
+    new KeyBinding('backspace'),
+    new KeyBinding('ctrl+h'),
+  ],
+  [Command.DELETE_CHAR_RIGHT]: [
+    new KeyBinding('delete'),
+    new KeyBinding('ctrl+d'),
+  ],
+  [Command.UNDO]: [new KeyBinding('cmd+z'), new KeyBinding('alt+z')],
+  [Command.REDO]: [
+    new KeyBinding('ctrl+shift+z'),
+    new KeyBinding('cmd+shift+z'),
+    new KeyBinding('alt+shift+z'),
+  ],
+
+  // Scrolling
+  [Command.SCROLL_UP]: [new KeyBinding('shift+up')],
+  [Command.SCROLL_DOWN]: [new KeyBinding('shift+down')],
+  [Command.SCROLL_HOME]: [
+    new KeyBinding('ctrl+home'),
+    new KeyBinding('shift+home'),
+  ],
+  [Command.SCROLL_END]: [
+    new KeyBinding('ctrl+end'),
+    new KeyBinding('shift+end'),
+  ],
+  [Command.PAGE_UP]: [new KeyBinding('pageup')],
+  [Command.PAGE_DOWN]: [new KeyBinding('pagedown')],
+
+  // History & Search
+  [Command.HISTORY_UP]: [new KeyBinding('ctrl+p')],
+  [Command.HISTORY_DOWN]: [new KeyBinding('ctrl+n')],
+  [Command.REVERSE_SEARCH]: [new KeyBinding('ctrl+r')],
+  [Command.SUBMIT_REVERSE_SEARCH]: [new KeyBinding('return')],
+  [Command.ACCEPT_SUGGESTION_REVERSE_SEARCH]: [new KeyBinding('tab')],
+
+  // Navigation
+  [Command.NAVIGATION_UP]: [new KeyBinding('up')],
+  [Command.NAVIGATION_DOWN]: [new KeyBinding('down')],
+  // Navigation shortcuts appropriate for dialogs where we do not need to accept
+  // text input.
+  [Command.DIALOG_NAVIGATION_UP]: [new KeyBinding('up'), new KeyBinding('k')],
+  [Command.DIALOG_NAVIGATION_DOWN]: [
+    new KeyBinding('down'),
+    new KeyBinding('j'),
+  ],
+  [Command.DIALOG_NEXT]: [new KeyBinding('tab')],
+  [Command.DIALOG_PREV]: [new KeyBinding('shift+tab')],
+
+  // Suggestions & Completions
+  [Command.ACCEPT_SUGGESTION]: [
+    new KeyBinding('tab'),
+    new KeyBinding('return'),
+  ],
+  [Command.COMPLETION_UP]: [new KeyBinding('up'), new KeyBinding('ctrl+p')],
+  [Command.COMPLETION_DOWN]: [new KeyBinding('down'), new KeyBinding('ctrl+n')],
+  [Command.EXPAND_SUGGESTION]: [new KeyBinding('right')],
+  [Command.COLLAPSE_SUGGESTION]: [new KeyBinding('left')],
+
+  // Text Input
+  // Must also exclude shift to allow shift+enter for newline
+  [Command.SUBMIT]: [new KeyBinding('return')],
+  [Command.NEWLINE]: [
+    new KeyBinding('ctrl+return'),
+    new KeyBinding('cmd+return'),
+    new KeyBinding('alt+return'),
+    new KeyBinding('shift+return'),
+    new KeyBinding('ctrl+j'),
+  ],
+  [Command.OPEN_EXTERNAL_EDITOR]: [new KeyBinding('ctrl+x')],
+  [Command.PASTE_CLIPBOARD]: [
+    new KeyBinding('ctrl+v'),
+    new KeyBinding('cmd+v'),
+    new KeyBinding('alt+v'),
+  ],
+
+  // App Controls
+  [Command.SHOW_ERROR_DETAILS]: [new KeyBinding('f12')],
+  [Command.SHOW_FULL_TODOS]: [new KeyBinding('ctrl+t')],
+  [Command.SHOW_IDE_CONTEXT_DETAIL]: [new KeyBinding('ctrl+g')],
+  [Command.TOGGLE_MARKDOWN]: [new KeyBinding('alt+m')],
+  [Command.TOGGLE_COPY_MODE]: [new KeyBinding('ctrl+s')],
+  [Command.TOGGLE_YOLO]: [new KeyBinding('ctrl+y')],
+  [Command.CYCLE_APPROVAL_MODE]: [new KeyBinding('shift+tab')],
+  [Command.TOGGLE_BACKGROUND_SHELL]: [new KeyBinding('ctrl+b')],
+  [Command.TOGGLE_BACKGROUND_SHELL_LIST]: [new KeyBinding('ctrl+l')],
+  [Command.KILL_BACKGROUND_SHELL]: [new KeyBinding('ctrl+k')],
+  [Command.UNFOCUS_BACKGROUND_SHELL]: [new KeyBinding('shift+tab')],
+  [Command.UNFOCUS_BACKGROUND_SHELL_LIST]: [new KeyBinding('tab')],
+  [Command.SHOW_BACKGROUND_SHELL_UNFOCUS_WARNING]: [new KeyBinding('tab')],
+  [Command.SHOW_SHELL_INPUT_UNFOCUS_WARNING]: [new KeyBinding('tab')],
+  [Command.BACKGROUND_SHELL_SELECT]: [new KeyBinding('return')],
+  [Command.BACKGROUND_SHELL_ESCAPE]: [new KeyBinding('escape')],
+  [Command.SHOW_MORE_LINES]: [new KeyBinding('ctrl+o')],
+  [Command.EXPAND_PASTE]: [new KeyBinding('ctrl+o')],
+  [Command.FOCUS_SHELL_INPUT]: [new KeyBinding('tab')],
+  [Command.UNFOCUS_SHELL_INPUT]: [new KeyBinding('shift+tab')],
+  [Command.CLEAR_SCREEN]: [new KeyBinding('ctrl+l')],
+  [Command.RESTART_APP]: [new KeyBinding('r'), new KeyBinding('shift+r')],
+  [Command.SUSPEND_APP]: [new KeyBinding('ctrl+z')],
+};
+
+interface CommandCategory {
+  readonly title: string;
+  readonly commands: readonly Command[];
+}
+
+/**
+ * Presentation metadata for grouping commands in documentation or UI.
+ */
+export const commandCategories: readonly CommandCategory[] = [
+  {
+    title: 'Basic Controls',
+    commands: [Command.RETURN, Command.ESCAPE, Command.QUIT, Command.EXIT],
+  },
+  {
+    title: 'Cursor Movement',
+    commands: [
+      Command.HOME,
+      Command.END,
+      Command.MOVE_UP,
+      Command.MOVE_DOWN,
+      Command.MOVE_LEFT,
+      Command.MOVE_RIGHT,
+      Command.MOVE_WORD_LEFT,
+      Command.MOVE_WORD_RIGHT,
+    ],
+  },
+  {
+    title: 'Editing',
+    commands: [
+      Command.KILL_LINE_RIGHT,
+      Command.KILL_LINE_LEFT,
+      Command.CLEAR_INPUT,
+      Command.DELETE_WORD_BACKWARD,
+      Command.DELETE_WORD_FORWARD,
+      Command.DELETE_CHAR_LEFT,
+      Command.DELETE_CHAR_RIGHT,
+      Command.UNDO,
+      Command.REDO,
+    ],
+  },
+  {
+    title: 'Scrolling',
+    commands: [
+      Command.SCROLL_UP,
+      Command.SCROLL_DOWN,
+      Command.SCROLL_HOME,
+      Command.SCROLL_END,
+      Command.PAGE_UP,
+      Command.PAGE_DOWN,
+    ],
+  },
+  {
+    title: 'History & Search',
+    commands: [
+      Command.HISTORY_UP,
+      Command.HISTORY_DOWN,
+      Command.REVERSE_SEARCH,
+      Command.SUBMIT_REVERSE_SEARCH,
+      Command.ACCEPT_SUGGESTION_REVERSE_SEARCH,
+    ],
+  },
+  {
+    title: 'Navigation',
+    commands: [
+      Command.NAVIGATION_UP,
+      Command.NAVIGATION_DOWN,
+      Command.DIALOG_NAVIGATION_UP,
+      Command.DIALOG_NAVIGATION_DOWN,
+      Command.DIALOG_NEXT,
+      Command.DIALOG_PREV,
+    ],
+  },
+  {
+    title: 'Suggestions & Completions',
+    commands: [
+      Command.ACCEPT_SUGGESTION,
+      Command.COMPLETION_UP,
+      Command.COMPLETION_DOWN,
+      Command.EXPAND_SUGGESTION,
+      Command.COLLAPSE_SUGGESTION,
+    ],
+  },
+  {
+    title: 'Text Input',
+    commands: [
+      Command.SUBMIT,
+      Command.NEWLINE,
+      Command.OPEN_EXTERNAL_EDITOR,
+      Command.PASTE_CLIPBOARD,
+    ],
+  },
+  {
+    title: 'App Controls',
+    commands: [
+      Command.SHOW_ERROR_DETAILS,
+      Command.SHOW_FULL_TODOS,
+      Command.SHOW_IDE_CONTEXT_DETAIL,
+      Command.TOGGLE_MARKDOWN,
+      Command.TOGGLE_COPY_MODE,
+      Command.TOGGLE_YOLO,
+      Command.CYCLE_APPROVAL_MODE,
+      Command.SHOW_MORE_LINES,
+      Command.EXPAND_PASTE,
+      Command.TOGGLE_BACKGROUND_SHELL,
+      Command.TOGGLE_BACKGROUND_SHELL_LIST,
+      Command.KILL_BACKGROUND_SHELL,
+      Command.BACKGROUND_SHELL_SELECT,
+      Command.BACKGROUND_SHELL_ESCAPE,
+      Command.UNFOCUS_BACKGROUND_SHELL,
+      Command.UNFOCUS_BACKGROUND_SHELL_LIST,
+      Command.SHOW_BACKGROUND_SHELL_UNFOCUS_WARNING,
+      Command.SHOW_SHELL_INPUT_UNFOCUS_WARNING,
+      Command.FOCUS_SHELL_INPUT,
+      Command.UNFOCUS_SHELL_INPUT,
+      Command.CLEAR_SCREEN,
+      Command.RESTART_APP,
+      Command.SUSPEND_APP,
+    ],
+  },
+];
+
+/**
+ * Human-readable descriptions for each command, used in docs/tooling.
+ */
+export const commandDescriptions: Readonly<Record<Command, string>> = {
+  // Basic Controls
+  [Command.RETURN]: 'Confirm the current selection or choice.',
+  [Command.ESCAPE]: 'Dismiss dialogs or cancel the current focus.',
+  [Command.QUIT]:
+    'Cancel the current request or quit the CLI when input is empty.',
+  [Command.EXIT]: 'Exit the CLI when the input buffer is empty.',
+
+  // Cursor Movement
+  [Command.HOME]: 'Move the cursor to the start of the line.',
+  [Command.END]: 'Move the cursor to the end of the line.',
+  [Command.MOVE_UP]: 'Move the cursor up one line.',
+  [Command.MOVE_DOWN]: 'Move the cursor down one line.',
+  [Command.MOVE_LEFT]: 'Move the cursor one character to the left.',
+  [Command.MOVE_RIGHT]: 'Move the cursor one character to the right.',
+  [Command.MOVE_WORD_LEFT]: 'Move the cursor one word to the left.',
+  [Command.MOVE_WORD_RIGHT]: 'Move the cursor one word to the right.',
+
+  // Editing
+  [Command.KILL_LINE_RIGHT]: 'Delete from the cursor to the end of the line.',
+  [Command.KILL_LINE_LEFT]: 'Delete from the cursor to the start of the line.',
+  [Command.CLEAR_INPUT]: 'Clear all text in the input field.',
+  [Command.DELETE_WORD_BACKWARD]: 'Delete the previous word.',
+  [Command.DELETE_WORD_FORWARD]: 'Delete the next word.',
+  [Command.DELETE_CHAR_LEFT]: 'Delete the character to the left.',
+  [Command.DELETE_CHAR_RIGHT]: 'Delete the character to the right.',
+  [Command.UNDO]: 'Undo the most recent text edit.',
+  [Command.REDO]: 'Redo the most recent undone text edit.',
+
+  // Scrolling
+  [Command.SCROLL_UP]: 'Scroll content up.',
+  [Command.SCROLL_DOWN]: 'Scroll content down.',
+  [Command.SCROLL_HOME]: 'Scroll to the top.',
+  [Command.SCROLL_END]: 'Scroll to the bottom.',
+  [Command.PAGE_UP]: 'Scroll up by one page.',
+  [Command.PAGE_DOWN]: 'Scroll down by one page.',
+
+  // History & Search
+  [Command.HISTORY_UP]: 'Show the previous entry in history.',
+  [Command.HISTORY_DOWN]: 'Show the next entry in history.',
+  [Command.REVERSE_SEARCH]: 'Start reverse search through history.',
+  [Command.SUBMIT_REVERSE_SEARCH]: 'Submit the selected reverse-search match.',
+  [Command.ACCEPT_SUGGESTION_REVERSE_SEARCH]:
+    'Accept a suggestion while reverse searching.',
+
+  // Navigation
+  [Command.NAVIGATION_UP]: 'Move selection up in lists.',
+  [Command.NAVIGATION_DOWN]: 'Move selection down in lists.',
+  [Command.DIALOG_NAVIGATION_UP]: 'Move up within dialog options.',
+  [Command.DIALOG_NAVIGATION_DOWN]: 'Move down within dialog options.',
+  [Command.DIALOG_NEXT]: 'Move to the next item or question in a dialog.',
+  [Command.DIALOG_PREV]: 'Move to the previous item or question in a dialog.',
+
+  // Suggestions & Completions
+  [Command.ACCEPT_SUGGESTION]: 'Accept the inline suggestion.',
+  [Command.COMPLETION_UP]: 'Move to the previous completion option.',
+  [Command.COMPLETION_DOWN]: 'Move to the next completion option.',
+  [Command.EXPAND_SUGGESTION]: 'Expand an inline suggestion.',
+  [Command.COLLAPSE_SUGGESTION]: 'Collapse an inline suggestion.',
+
+  // Text Input
+  [Command.SUBMIT]: 'Submit the current prompt.',
+  [Command.NEWLINE]: 'Insert a newline without submitting.',
+  [Command.OPEN_EXTERNAL_EDITOR]:
+    'Open the current prompt or the plan in an external editor.',
+  [Command.PASTE_CLIPBOARD]: 'Paste from the clipboard.',
+
+  // App Controls
+  [Command.SHOW_ERROR_DETAILS]: 'Toggle detailed error information.',
+  [Command.SHOW_FULL_TODOS]: 'Toggle the full TODO list.',
+  [Command.SHOW_IDE_CONTEXT_DETAIL]: 'Show IDE context details.',
+  [Command.TOGGLE_MARKDOWN]: 'Toggle Markdown rendering.',
+  [Command.TOGGLE_COPY_MODE]: 'Toggle copy mode when in alternate buffer mode.',
+  [Command.TOGGLE_YOLO]: 'Toggle YOLO (auto-approval) mode for tool calls.',
+  [Command.CYCLE_APPROVAL_MODE]:
+    'Cycle through approval modes: default (prompt), auto_edit (auto-approve edits), and plan (read-only). Plan mode is skipped when the agent is busy.',
+  [Command.SHOW_MORE_LINES]:
+    'Expand and collapse blocks of content when not in alternate buffer mode.',
+  [Command.EXPAND_PASTE]:
+    'Expand or collapse a paste placeholder when cursor is over placeholder.',
+  [Command.BACKGROUND_SHELL_SELECT]:
+    'Confirm selection in background shell list.',
+  [Command.BACKGROUND_SHELL_ESCAPE]: 'Dismiss background shell list.',
+  [Command.TOGGLE_BACKGROUND_SHELL]:
+    'Toggle current background shell visibility.',
+  [Command.TOGGLE_BACKGROUND_SHELL_LIST]: 'Toggle background shell list.',
+  [Command.KILL_BACKGROUND_SHELL]: 'Kill the active background shell.',
+  [Command.UNFOCUS_BACKGROUND_SHELL]:
+    'Move focus from background shell to Gemini.',
+  [Command.UNFOCUS_BACKGROUND_SHELL_LIST]:
+    'Move focus from background shell list to Gemini.',
+  [Command.SHOW_BACKGROUND_SHELL_UNFOCUS_WARNING]:
+    'Show warning when trying to move focus away from background shell.',
+  [Command.SHOW_SHELL_INPUT_UNFOCUS_WARNING]:
+    'Show warning when trying to move focus away from shell input.',
+  [Command.FOCUS_SHELL_INPUT]: 'Move focus from Gemini to the active shell.',
+  [Command.UNFOCUS_SHELL_INPUT]: 'Move focus from the shell back to Gemini.',
+  [Command.CLEAR_SCREEN]: 'Clear the terminal screen and redraw the UI.',
+  [Command.RESTART_APP]: 'Restart the application.',
+  [Command.SUSPEND_APP]: 'Suspend the CLI and move it to the background.',
+};

packages/cli/src/ui/key/keyMatchers.test.ts

@@ -10,9 +10,9 @@ import {
   Command,
   createKeyMatchers,
 } from './keyMatchers.js';
-import type { KeyBindingConfig } from '../config/keyBindings.js';
-import { defaultKeyBindings } from '../config/keyBindings.js';
-import type { Key } from './hooks/useKeypress.js';
+import type { KeyBindingConfig } from './keyBindings.js';
+import { defaultKeyBindings, KeyBinding } from './keyBindings.js';
+import type { Key } from '../hooks/useKeypress.js';
 
 describe('keyMatchers', () => {
   const createKey = (name: string, mods: Partial<Key> = {}): Key => ({
@@ -445,7 +445,7 @@ describe('keyMatchers', () => {
     it('should work with custom configuration', () => {
       const customConfig: KeyBindingConfig = {
         ...defaultKeyBindings,
-        [Command.HOME]: [{ key: 'h', ctrl: true }, { key: '0' }],
+        [Command.HOME]: [new KeyBinding('ctrl+h'), new KeyBinding('0')],
       };
 
       const customMatchers = createKeyMatchers(customConfig);
@@ -462,10 +462,7 @@ describe('keyMatchers', () => {
     it('should support multiple key bindings for same command', () => {
       const config: KeyBindingConfig = {
         ...defaultKeyBindings,
-        [Command.QUIT]: [
-          { key: 'q', ctrl: true },
-          { key: 'q', alt: true },
-        ],
+        [Command.QUIT]: [new KeyBinding('ctrl+q'), new KeyBinding('alt+q')],
       };
 
       const matchers = createKeyMatchers(config);

packages/cli/src/ui/key/keyMatchers.ts

@@ -4,26 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { Key } from './hooks/useKeypress.js';
-import type { KeyBinding, KeyBindingConfig } from '../config/keyBindings.js';
-import { Command, defaultKeyBindings } from '../config/keyBindings.js';
-
-/**
- * Matches a KeyBinding against an actual Key press
- * Pure data-driven matching logic
- */
-function matchKeyBinding(keyBinding: KeyBinding, key: Key): boolean {
-  // Check modifiers:
-  // true = modifier must be pressed
-  // false or undefined = modifier must NOT be pressed
-  return (
-    keyBinding.key === key.name &&
-    !!key.shift === !!keyBinding.shift &&
-    !!key.alt === !!keyBinding.alt &&
-    !!key.ctrl === !!keyBinding.ctrl &&
-    !!key.cmd === !!keyBinding.cmd
-  );
-}
+import type { Key } from '../hooks/useKeypress.js';
+import type { KeyBindingConfig } from './keyBindings.js';
+import { Command, defaultKeyBindings } from './keyBindings.js';
 
 /**
  * Checks if a key matches any of the bindings for a command
@@ -33,8 +16,7 @@ function matchCommand(
   key: Key,
   config: KeyBindingConfig = defaultKeyBindings,
 ): boolean {
-  const bindings = config[command];
-  return bindings.some((binding) => matchKeyBinding(binding, key));
+  return config[command].some((binding) => binding.matches(key));
 }
 
 /**

packages/cli/src/ui/key/keyToAnsi.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Key } from '../contexts/KeypressContext.js';
+
+export type { Key };
+
+const SPECIAL_KEYS: Record<string, string> = {
+  up: '\x1b[A',
+  down: '\x1b[B',
+  right: '\x1b[C',
+  left: '\x1b[D',
+  escape: '\x1b',
+  tab: '\t',
+  backspace: '\x7f',
+  delete: '\x1b[3~',
+  home: '\x1b[H',
+  end: '\x1b[F',
+  pageup: '\x1b[5~',
+  pagedown: '\x1b[6~',
+  return: '\r',
+};
+
+/**
+ * Translates a Key object into its corresponding ANSI escape sequence.
+ * This is useful for sending control characters to a pseudo-terminal.
+ *
+ * @param key The Key object to translate.
+ * @returns The ANSI escape sequence as a string, or null if no mapping exists.
+ */
+export function keyToAnsi(key: Key): string | null {
+  if (key.ctrl) {
+    // Ctrl + letter (A-Z maps to 1-26, e.g., Ctrl+C is \x03)
+    if (key.name >= 'a' && key.name <= 'z') {
+      return String.fromCharCode(
+        key.name.charCodeAt(0) - 'a'.charCodeAt(0) + 1,
+      );
+    }
+  }
+
+  // Arrow keys and other special keys
+  if (key.name in SPECIAL_KEYS) {
+    return SPECIAL_KEYS[key.name];
+  }
+
+  // If it's a simple character, return it.
+  if (!key.ctrl && !key.cmd && key.sequence) {
+    return key.sequence;
+  }
+
+  return null;
+}

packages/cli/src/ui/key/keybindingUtils.test.ts

@@ -6,8 +6,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { formatKeyBinding, formatCommand } from './keybindingUtils.js';
-import { Command } from '../../config/keyBindings.js';
-import type { KeyBinding } from '../../config/keyBindings.js';
+import { Command, KeyBinding } from './keyBindings.js';
 
 describe('keybindingUtils', () => {
   describe('formatKeyBinding', () => {
@@ -23,12 +22,12 @@ describe('keybindingUtils', () => {
     }> = [
       {
         name: 'simple key',
-        binding: { key: 'a' },
+        binding: new KeyBinding('a'),
         expected: { darwin: 'A', win32: 'A', linux: 'A', default: 'A' },
       },
       {
         name: 'named key (return)',
-        binding: { key: 'return' },
+        binding: new KeyBinding('return'),
         expected: {
           darwin: 'Enter',
           win32: 'Enter',
@@ -38,12 +37,12 @@ describe('keybindingUtils', () => {
       },
       {
         name: 'named key (escape)',
-        binding: { key: 'escape' },
+        binding: new KeyBinding('escape'),
         expected: { darwin: 'Esc', win32: 'Esc', linux: 'Esc', default: 'Esc' },
       },
       {
         name: 'ctrl modifier',
-        binding: { key: 'c', ctrl: true },
+        binding: new KeyBinding('ctrl+c'),
         expected: {
           darwin: 'Ctrl+C',
           win32: 'Ctrl+C',
@@ -53,7 +52,7 @@ describe('keybindingUtils', () => {
       },
       {
         name: 'cmd modifier',
-        binding: { key: 'z', cmd: true },
+        binding: new KeyBinding('cmd+z'),
         expected: {
           darwin: 'Cmd+Z',
           win32: 'Win+Z',
@@ -63,7 +62,7 @@ describe('keybindingUtils', () => {
       },
       {
         name: 'alt/option modifier',
-        binding: { key: 'left', alt: true },
+        binding: new KeyBinding('alt+left'),
         expected: {
           darwin: 'Option+Left',
           win32: 'Alt+Left',
@@ -73,7 +72,7 @@ describe('keybindingUtils', () => {
       },
       {
         name: 'shift modifier',
-        binding: { key: 'up', shift: true },
+        binding: new KeyBinding('shift+up'),
         expected: {
           darwin: 'Shift+Up',
           win32: 'Shift+Up',
@@ -83,7 +82,7 @@ describe('keybindingUtils', () => {
       },
       {
         name: 'multiple modifiers (ctrl+shift)',
-        binding: { key: 'z', ctrl: true, shift: true },
+        binding: new KeyBinding('ctrl+shift+z'),
         expected: {
           darwin: 'Ctrl+Shift+Z',
           win32: 'Ctrl+Shift+Z',
@@ -93,7 +92,7 @@ describe('keybindingUtils', () => {
       },
       {
         name: 'all modifiers',
-        binding: { key: 'a', ctrl: true, alt: true, shift: true, cmd: true },
+        binding: new KeyBinding('ctrl+alt+shift+cmd+a'),
         expected: {
           darwin: 'Ctrl+Option+Shift+Cmd+A',
           win32: 'Ctrl+Alt+Shift+Win+A',

packages/cli/src/ui/key/keybindingUtils.ts

@@ -10,7 +10,7 @@ import {
   type KeyBinding,
   type KeyBindingConfig,
   defaultKeyBindings,
-} from '../../config/keyBindings.js';
+} from './keyBindings.js';
 
 /**
  * Maps internal key names to user-friendly display names.
@@ -30,7 +30,6 @@ const KEY_NAME_MAP: Record<string, string> = {
   end: 'End',
   tab: 'Tab',
   space: 'Space',
-  'double escape': 'Double Esc',
 };
 
 interface ModifierMap {

packages/cli/src/ui/utils/shortcutsHelp.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Command } from '../keyMatchers.js';
+import { Command } from '../key/keyMatchers.js';
 import type { Key } from '../hooks/useKeypress.js';
 import { useKeyMatchers } from '../hooks/useKeyMatchers.js';