Add chord keyboard shortcuts and staged capture UI

2026-07-29 12:01:31 +00:00 · 2026-03-22 16:28:09 +07:00
parent d9bcf2a439
commit 57f8c7615c
16 changed files with 498 additions and 99 deletions
--- a/packages/app/src/components/agent-input-area.tsx
+++ b/packages/app/src/components/agent-input-area.tsx
@@ -594,12 +594,14 @@ export function AgentInputArea({
          )}
        </TooltipTrigger>
        <TooltipContent side="top" align="center" offset={8}>
-          <View style={styles.tooltipRow}>
-            <Text style={styles.tooltipText}>Interrupt</Text>
-            {dictationCancelKeys ? <Shortcut keys={dictationCancelKeys} style={styles.tooltipShortcut} /> : null}
-          </View>
-        </TooltipContent>
-      </Tooltip>
+            <View style={styles.tooltipRow}>
+              <Text style={styles.tooltipText}>Interrupt</Text>
+              {dictationCancelKeys ? (
+                <Shortcut chord={dictationCancelKeys} style={styles.tooltipShortcut} />
+              ) : null}
+            </View>
+          </TooltipContent>
+        </Tooltip>
    ) : null;

  const rightContent = (
@@ -626,7 +628,9 @@ export function AgentInputArea({
          <TooltipContent side="top" align="center" offset={8}>
            <View style={styles.tooltipRow}>
              <Text style={styles.tooltipText}>Voice mode</Text>
-              {voiceToggleKeys && <Shortcut keys={voiceToggleKeys} style={styles.tooltipShortcut} />}
+              {voiceToggleKeys ? (
+                <Shortcut chord={voiceToggleKeys} style={styles.tooltipShortcut} />
+              ) : null}
            </View>
          </TooltipContent>
        </Tooltip>
--- a/packages/app/src/components/command-center.tsx
+++ b/packages/app/src/components/command-center.tsx
@@ -178,7 +178,7 @@ export function CommandCenter() {
                              </View>
                            </View>
                            {action.shortcutKeys ? (
-                              <Shortcut keys={action.shortcutKeys} style={styles.rowShortcut} />
+                              <Shortcut chord={action.shortcutKeys} style={styles.rowShortcut} />
                            ) : null}
                          </View>
                        </CommandCenterRow>
--- a/packages/app/src/components/left-sidebar.tsx
+++ b/packages/app/src/components/left-sidebar.tsx
@@ -565,7 +565,7 @@ function MobileSidebar({
                  <TooltipContent side="top" align="center" offset={8}>
                    <View style={styles.tooltipRow}>
                      <Text style={styles.tooltipText}>Add project</Text>
-                      {newAgentKeys && <Shortcut keys={newAgentKeys} />}
+                      {newAgentKeys ? <Shortcut chord={newAgentKeys} /> : null}
                    </View>
                  </TooltipContent>
                </Tooltip>
@@ -745,7 +745,7 @@ function DesktopSidebar({
            <TooltipContent side="top" align="center" offset={8}>
              <View style={styles.tooltipRow}>
                <Text style={styles.tooltipText}>Add project</Text>
-                {newAgentKeys ? <Shortcut keys={newAgentKeys} /> : null}
+                {newAgentKeys ? <Shortcut chord={newAgentKeys} /> : null}
              </View>
            </TooltipContent>
          </Tooltip>
--- a/packages/app/src/components/message-input.tsx
+++ b/packages/app/src/components/message-input.tsx
@@ -1013,7 +1013,11 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(funct
                  </Text>
                  {(isRealtimeVoiceForCurrentAgent ? voiceMuteToggleKeys : dictationToggleKeys) ? (
                    <Shortcut
-                      keys={(isRealtimeVoiceForCurrentAgent ? voiceMuteToggleKeys : dictationToggleKeys)!}
+                      chord={
+                        (isRealtimeVoiceForCurrentAgent
+                          ? voiceMuteToggleKeys
+                          : dictationToggleKeys)!
+                      }
                      style={styles.tooltipShortcut}
                    />
                  ) : null}
@@ -1039,7 +1043,9 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(funct
                <TooltipContent side="top" align="center" offset={8}>
                  <View style={styles.tooltipRow}>
                    <Text style={styles.tooltipText}>Queue</Text>
-                    {queueKeys ? <Shortcut keys={queueKeys} style={styles.tooltipShortcut} /> : null}
+                    {queueKeys ? (
+                      <Shortcut chord={queueKeys} style={styles.tooltipShortcut} />
+                    ) : null}
                  </View>
                </TooltipContent>
              </Tooltip>
@@ -1062,7 +1068,7 @@ export const MessageInput = forwardRef<MessageInputRef, MessageInputProps>(funct
                <TooltipContent side="top" align="center" offset={8}>
                  <View style={styles.tooltipRow}>
                    <Text style={styles.tooltipText}>Send</Text>
-                    {sendKeys ? <Shortcut keys={sendKeys} style={styles.tooltipShortcut} /> : null}
+                    {sendKeys ? <Shortcut chord={sendKeys} style={styles.tooltipShortcut} /> : null}
                  </View>
                </TooltipContent>
              </Tooltip>
--- a/packages/app/src/components/sidebar-workspace-list.tsx
+++ b/packages/app/src/components/sidebar-workspace-list.tsx
@@ -150,7 +150,7 @@ interface WorkspaceRowInnerProps {
  onArchive?: () => void;
  onCopyBranchName?: () => void;
  onCopyPath?: () => void;
-  archiveShortcutKeys?: ShortcutKey[] | null;
+  archiveShortcutKeys?: ShortcutKey[][] | null;
 }

 function resolveStatusDotColor(input: {
@@ -322,7 +322,7 @@ function NewWorktreeButton({
          <View style={styles.projectActionTooltipRow}>
            <Text style={styles.projectActionTooltipText}>New worktree</Text>
            {showShortcutHint && newWorktreeKeys ? (
-              <Shortcut keys={newWorktreeKeys} style={styles.projectActionTooltipShortcut} />
+              <Shortcut chord={newWorktreeKeys} style={styles.projectActionTooltipShortcut} />
            ) : null}
          </View>
        </TooltipContent>
@@ -842,7 +842,7 @@ function WorkspaceRowInner({
                <DropdownMenuItem
                  testID={`sidebar-workspace-menu-archive-${workspace.workspaceKey}`}
                  leading={<Archive size={14} color={theme.colors.foregroundMuted} />}
-                  trailing={archiveShortcutKeys ? <Shortcut keys={archiveShortcutKeys} /> : null}
+                  trailing={archiveShortcutKeys ? <Shortcut chord={archiveShortcutKeys} /> : null}
                  status={archiveStatus}
                  pendingLabel={archivePendingLabel}
                  onSelect={onArchive}
--- a/packages/app/src/components/ui/shortcut.tsx
+++ b/packages/app/src/components/ui/shortcut.tsx
@@ -6,22 +6,49 @@ import { getShortcutOs } from "@/utils/shortcut-platform";

 export function Shortcut({
  keys,
+  chord,
  style,
  textStyle,
 }: {
-  keys: ShortcutKey[];
+  keys?: ShortcutKey[];
+  chord?: ShortcutKey[][];
  style?: StyleProp<ViewStyle>;
  textStyle?: StyleProp<TextStyle>;
 }): ReactElement {
+  const displayChord = chord ?? (keys ? [keys] : []);
+  const shortcutOs = getShortcutOs();
+  const singleCombo = displayChord[0];
+
+  if (!singleCombo) {
+    return <View style={style} />;
+  }
+
+  if (displayChord.length === 1) {
+    return (
+      <View style={[styles.badge, style]}>
+        <Text style={[styles.text, textStyle]}>{formatShortcut(singleCombo, shortcutOs)}</Text>
+      </View>
+    );
+  }
+
  return (
-    <View style={[styles.root, style]}>
-      <Text style={[styles.text, textStyle]}>{formatShortcut(keys, getShortcutOs())}</Text>
+    <View style={[styles.sequence, style]}>
+      {displayChord.map(function (combo, index) {
+        return (
+          <View key={`${combo.join("+")}-${index}`} style={styles.sequenceItem}>
+            <View style={styles.badge}>
+              <Text style={[styles.text, textStyle]}>{formatShortcut(combo, shortcutOs)}</Text>
+            </View>
+            {index < displayChord.length - 1 ? <Text style={styles.separator}>→</Text> : null}
+          </View>
+        );
+      })}
    </View>
  );
 }

 const styles = StyleSheet.create((theme) => ({
-  root: {
+  badge: {
    paddingHorizontal: theme.spacing[1],
    paddingVertical: 2,
    borderRadius: theme.borderRadius.md,
@@ -29,6 +56,21 @@ const styles = StyleSheet.create((theme) => ({
    borderWidth: theme.borderWidth[1],
    borderColor: theme.colors.borderAccent,
  },
+  sequence: {
+    flexDirection: "row",
+    alignItems: "center",
+    flexWrap: "wrap",
+    gap: theme.spacing[1],
+  },
+  sequenceItem: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[1],
+  },
+  separator: {
+    fontSize: theme.fontSize.xs,
+    color: theme.colors.foregroundMuted,
+  },
  text: {
    fontSize: theme.fontSize.xs,
    fontWeight: theme.fontWeight.normal,
--- a/packages/app/src/hooks/use-command-center.ts
+++ b/packages/app/src/hooks/use-command-center.ts
@@ -13,7 +13,7 @@ import {
 } from "@/utils/command-center-focus-restore";
 import { buildHostSettingsRoute, parseServerIdFromPathname } from "@/utils/host-routes";
 import type { ShortcutKey } from "@/utils/format-shortcut";
-import { comboStringToShortcutKeys } from "@/keyboard/shortcut-string";
+import { chordStringToShortcutKeys } from "@/keyboard/shortcut-string";
 import { getBindingIdForAction, getDefaultKeysForAction } from "@/keyboard/keyboard-shortcuts";
 import { useKeyboardShortcutOverrides } from "@/hooks/use-keyboard-shortcut-overrides";
 import { getShortcutOs } from "@/utils/shortcut-platform";
@@ -91,7 +91,7 @@ export type CommandCenterActionItem = {
  title: string;
  icon?: "plus" | "settings";
  route?: Href;
-  shortcutKeys?: ShortcutKey[];
+  shortcutKeys?: ShortcutKey[][];
 };

 export type CommandCenterItem =
@@ -107,7 +107,7 @@ export type CommandCenterItem =
 function resolveActionShortcutKeys(
  actionId: string | undefined,
  overrides: Record<string, string>,
-): ShortcutKey[] | undefined {
+): ShortcutKey[][] | undefined {
  if (!actionId) return undefined;
  const isMac = getShortcutOs() === "mac";
  const isDesktop = getIsDesktop();
@@ -115,8 +115,9 @@ function resolveActionShortcutKeys(
  const bindingId = getBindingIdForAction(actionId, platform);
  if (!bindingId) return undefined;
  const override = overrides[bindingId];
-  if (override) return comboStringToShortcutKeys(override);
-  return getDefaultKeysForAction(actionId, platform) ?? undefined;
+  if (override) return chordStringToShortcutKeys(override);
+  const defaultKeys = getDefaultKeysForAction(actionId, platform);
+  return defaultKeys ? [defaultKeys] : undefined;
 }

 export function useCommandCenter() {
--- a/packages/app/src/hooks/use-keyboard-shortcuts.ts
+++ b/packages/app/src/hooks/use-keyboard-shortcuts.ts
@@ -1,4 +1,4 @@
-import { useEffect, useMemo } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { Platform } from "react-native";
 import { usePathname } from "expo-router";
 import { getIsDesktop } from "@/constants/layout";
@@ -17,7 +17,11 @@ import {
 } from "@/keyboard/actions";
 import { canToggleFileExplorerShortcut } from "@/keyboard/keyboard-shortcut-routing";
 import { keyboardActionDispatcher } from "@/keyboard/keyboard-action-dispatcher";
-import { resolveKeyboardShortcut, buildEffectiveBindings } from "@/keyboard/keyboard-shortcuts";
+import {
+  type ChordState,
+  resolveKeyboardShortcut,
+  buildEffectiveBindings,
+} from "@/keyboard/keyboard-shortcuts";
 import { resolveKeyboardFocusScope } from "@/keyboard/focus-scope";
 import { getShortcutOs } from "@/utils/shortcut-platform";
 import { useOpenProjectPicker } from "@/hooks/use-open-project-picker";
@@ -41,6 +45,11 @@ export function useKeyboardShortcuts({
  const resetModifiers = useKeyboardShortcutsStore((s) => s.resetModifiers);
  const { overrides } = useKeyboardShortcutOverrides();
  const bindings = useMemo(() => buildEffectiveBindings(overrides), [overrides]);
+  const chordStateRef = useRef<ChordState>({
+    candidateIndices: [],
+    step: 0,
+    timeoutId: null,
+  });
  const activeServerIdFromPath = parseServerIdFromPathname(pathname);
  const activeServerId =
    hosts.find((host) => host.serverId === activeServerIdFromPath)?.serverId ??
@@ -271,6 +280,11 @@ export function useKeyboardShortcuts({
        return;
      }

+      const store = useKeyboardShortcutsStore.getState();
+      if (store.capturingShortcut) {
+        return;
+      }
+
      const key = event.key ?? "";
      if (key === "Alt" && !event.shiftKey) {
        useKeyboardShortcutsStore.getState().setAltDown(true);
@@ -285,12 +299,11 @@ export function useKeyboardShortcuts({
        }
      }

-      const store = useKeyboardShortcutsStore.getState();
      const focusScope = resolveKeyboardFocusScope({
        target: event.target,
        commandCenterOpen: store.commandCenterOpen,
      });
-      const match = resolveKeyboardShortcut({
+      const result = resolveKeyboardShortcut({
        event,
        context: {
          isMac,
@@ -303,25 +316,41 @@ export function useKeyboardShortcuts({
            toggleFileExplorer,
          }),
        },
+        chordState: chordStateRef.current,
+        onChordReset: () => {
+          chordStateRef.current = {
+            candidateIndices: [],
+            step: 0,
+            timeoutId: null,
+          };
+        },
        bindings,
      });
-      if (!match) {
+
+      chordStateRef.current = result.nextChordState;
+
+      if (result.preventDefault) {
+        event.preventDefault();
+        event.stopPropagation();
+      }
+
+      if (!result.match) {
        return;
      }

      const handled = handleAction({
-        action: match.action,
-        payload: match.payload,
+        action: result.match.action,
+        payload: result.match.payload,
        event,
      });
      if (!handled) {
        return;
      }

-      if (match.preventDefault) {
+      if (result.match.preventDefault) {
        event.preventDefault();
      }
-      if (match.stopPropagation) {
+      if (result.match.stopPropagation) {
        event.stopPropagation();
      }
    };
@@ -345,6 +374,14 @@ export function useKeyboardShortcuts({
    window.addEventListener("blur", handleBlurOrHide);
    document.addEventListener("visibilitychange", handleBlurOrHide);
    return () => {
+      if (chordStateRef.current.timeoutId !== null) {
+        clearTimeout(chordStateRef.current.timeoutId);
+        chordStateRef.current = {
+          candidateIndices: [],
+          step: 0,
+          timeoutId: null,
+        };
+      }
      window.removeEventListener("keydown", handleKeyDown, true);
      window.removeEventListener("keyup", handleKeyUp, true);
      window.removeEventListener("blur", handleBlurOrHide);
--- a/packages/app/src/hooks/use-shortcut-keys.ts
+++ b/packages/app/src/hooks/use-shortcut-keys.ts
@@ -1,12 +1,12 @@
 import { useMemo } from "react";
 import type { ShortcutKey } from "@/utils/format-shortcut";
-import { comboStringToShortcutKeys } from "@/keyboard/shortcut-string";
+import { chordStringToShortcutKeys } from "@/keyboard/shortcut-string";
 import { getBindingIdForAction, getDefaultKeysForAction } from "@/keyboard/keyboard-shortcuts";
 import { useKeyboardShortcutOverrides } from "@/hooks/use-keyboard-shortcut-overrides";
 import { getShortcutOs } from "@/utils/shortcut-platform";
 import { getIsDesktop } from "@/constants/layout";

-export function useShortcutKeys(actionId: string): ShortcutKey[] | null {
+export function useShortcutKeys(actionId: string): ShortcutKey[][] | null {
  const { overrides } = useKeyboardShortcutOverrides();
  const isMac = getShortcutOs() === "mac";
  const isDesktop = getIsDesktop();
@@ -18,9 +18,10 @@ export function useShortcutKeys(actionId: string): ShortcutKey[] | null {

    const override = overrides[bindingId];
    if (override) {
-      return comboStringToShortcutKeys(override);
+      return chordStringToShortcutKeys(override);
    }

-    return getDefaultKeysForAction(actionId, platform);
+    const defaultKeys = getDefaultKeysForAction(actionId, platform);
+    return defaultKeys ? [defaultKeys] : null;
  }, [actionId, overrides, isMac, isDesktop]);
 }
--- a/packages/app/src/keyboard/keyboard-shortcuts.test.ts
+++ b/packages/app/src/keyboard/keyboard-shortcuts.test.ts
@@ -1,8 +1,11 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import {
  buildKeyboardShortcutHelpSections,
+  buildEffectiveBindings,
  resolveKeyboardShortcut,
+  type ChordState,
  type KeyboardShortcutContext,
+  type ParsedShortcutBinding,
 } from "./keyboard-shortcuts";

 function keyboardEvent(overrides: Partial<KeyboardEvent>): KeyboardEvent {
@@ -31,6 +34,30 @@ function shortcutContext(
  };
 }

+function initialChordState(): ChordState {
+  return {
+    candidateIndices: [],
+    step: 0,
+    timeoutId: null,
+  };
+}
+
+function resolveShortcut(input: {
+  event: Partial<KeyboardEvent>;
+  context?: Partial<KeyboardShortcutContext>;
+  chordState?: ChordState;
+  onChordReset?: () => void;
+  bindings?: readonly ParsedShortcutBinding[];
+}) {
+  return resolveKeyboardShortcut({
+    event: keyboardEvent(input.event),
+    context: shortcutContext(input.context),
+    chordState: input.chordState ?? initialChordState(),
+    onChordReset: input.onChordReset ?? (() => undefined),
+    ...(input.bindings ? { bindings: input.bindings } : {}),
+  });
+}
+
 function expectShortcutResolution(input: {
  event: Partial<KeyboardEvent>;
  context?: Partial<KeyboardShortcutContext>;
@@ -39,29 +66,33 @@ function expectShortcutResolution(input: {
  preventDefault?: boolean;
  stopPropagation?: boolean;
 }) {
-  const match = resolveKeyboardShortcut({
-    event: keyboardEvent(input.event),
-    context: shortcutContext(input.context),
+  const result = resolveShortcut({
+    event: input.event,
+    context: input.context,
  });

-  expect(match?.action).toBe(input.action);
+  expect(result.match?.action).toBe(input.action);
  if ("payload" in input) {
-    expect(match?.payload).toEqual(input.payload);
+    expect(result.match?.payload).toEqual(input.payload);
  }
-  expect(match?.preventDefault).toBe(input.preventDefault ?? true);
-  expect(match?.stopPropagation).toBe(input.stopPropagation ?? true);
+  expect(result.match?.preventDefault).toBe(input.preventDefault ?? true);
+  expect(result.match?.stopPropagation).toBe(input.stopPropagation ?? true);
+  expect(result.preventDefault).toBe(false);
+  expect(result.nextChordState).toEqual(initialChordState());
 }

 function expectNoShortcutResolution(input: {
  event: Partial<KeyboardEvent>;
  context?: Partial<KeyboardShortcutContext>;
 }) {
-  const match = resolveKeyboardShortcut({
-    event: keyboardEvent(input.event),
-    context: shortcutContext(input.context),
+  const result = resolveShortcut({
+    event: input.event,
+    context: input.context,
  });

-  expect(match).toBeNull();
+  expect(result.match).toBeNull();
+  expect(result.preventDefault).toBe(false);
+  expect(result.nextChordState).toEqual(initialChordState());
 }

 type MatchingShortcutCase = {
@@ -338,6 +369,66 @@ describe("keyboard-shortcuts", () => {
  it.each(nonMatchingCases)("$name", ({ event, context }) => {
    expectNoShortcutResolution({ event, context });
  });
+
+  it("prefers advancing chord candidates over single-combo matches on the same prefix", () => {
+    const bindings = buildEffectiveBindings({
+      "workspace-terminal-new-ctrl-shift-t-non-mac": "Ctrl+W S",
+    });
+    const chordBindingIndex = bindings.findIndex(
+      (binding) => binding.id === "workspace-terminal-new-ctrl-shift-t-non-mac",
+    );
+    expect(chordBindingIndex).toBeGreaterThan(-1);
+
+    const firstResult = resolveShortcut({
+      event: { key: "w", code: "KeyW", ctrlKey: true },
+      context: { isMac: false, isDesktop: true },
+      bindings,
+    });
+
+    expect(firstResult.match).toBeNull();
+    expect(firstResult.preventDefault).toBe(true);
+    expect(firstResult.nextChordState.step).toBe(1);
+    expect(firstResult.nextChordState.candidateIndices).toEqual([chordBindingIndex]);
+
+    const secondResult = resolveShortcut({
+      event: { key: "s", code: "KeyS" },
+      context: { isMac: false, isDesktop: true },
+      chordState: firstResult.nextChordState,
+      bindings,
+    });
+
+    expect(secondResult.match?.action).toBe("workspace.terminal.new");
+    expect(secondResult.match?.payload).toBeNull();
+    expect(secondResult.match?.preventDefault).toBe(true);
+    expect(secondResult.match?.stopPropagation).toBe(true);
+    expect(secondResult.preventDefault).toBe(false);
+    expect(secondResult.nextChordState).toEqual(initialChordState());
+  });
+
+  it("schedules a chord reset timeout for advancing candidates", () => {
+    vi.useFakeTimers();
+
+    const bindings = buildEffectiveBindings({
+      "workspace-terminal-new-ctrl-shift-t-non-mac": "Ctrl+W S",
+    });
+    const onChordReset = vi.fn();
+
+    const result = resolveShortcut({
+      event: { key: "w", code: "KeyW", ctrlKey: true },
+      context: { isMac: false, isDesktop: true },
+      onChordReset,
+      bindings,
+    });
+
+    expect(result.match).toBeNull();
+    expect(result.preventDefault).toBe(true);
+    expect(result.nextChordState.timeoutId).not.toBeNull();
+
+    vi.advanceTimersByTime(1500);
+
+    expect(onChordReset).toHaveBeenCalledTimes(1);
+    vi.useRealTimers();
+  });
 });

 describe("keyboard-shortcut help sections", () => {
--- a/packages/app/src/keyboard/keyboard-shortcuts.ts
+++ b/packages/app/src/keyboard/keyboard-shortcuts.ts
@@ -5,7 +5,7 @@ import type {
  KeyboardShortcutPayload,
  MessageInputKeyboardActionKind,
 } from "@/keyboard/actions";
-import { type KeyCombo, parseShortcutString } from "@/keyboard/shortcut-string";
+import { type KeyCombo, parseChordString } from "@/keyboard/shortcut-string";

 export type { KeyCombo } from "@/keyboard/shortcut-string";

@@ -88,7 +88,13 @@ interface ShortcutBinding {
 }

 export interface ParsedShortcutBinding extends ShortcutBinding {
-  parsedCombo: KeyCombo;
+  parsedChord: KeyCombo[];
+}
+
+export interface ChordState {
+  candidateIndices: number[];
+  step: number;
+  timeoutId: ReturnType<typeof setTimeout> | null;
 }

 // --- Constants ---
@@ -817,11 +823,12 @@ const SHORTCUT_BINDINGS: readonly ShortcutBinding[] = [
 // --- Parse bindings at module load ---

 function parseBinding(binding: ShortcutBinding): ParsedShortcutBinding {
-  const parsedCombo = parseShortcutString(binding.combo);
-  if (binding.repeat === false) {
-    parsedCombo.repeat = false;
+  const parsedChord = parseChordString(binding.combo);
+  const lastCombo = parsedChord.at(-1);
+  if (binding.repeat === false && lastCombo) {
+    lastCombo.repeat = false;
  }
-  return { ...binding, parsedCombo };
+  return { ...binding, parsedChord };
 }

 export const DEFAULT_BINDINGS: readonly ParsedShortcutBinding[] =
@@ -835,16 +842,17 @@ export function buildEffectiveBindings(
    if (override === undefined) {
      return binding;
    }
-    let parsedCombo: KeyCombo;
+    let parsedChord: KeyCombo[];
    try {
-      parsedCombo = parseShortcutString(override);
+      parsedChord = parseChordString(override);
    } catch {
      return binding;
    }
-    if (binding.repeat === false) {
-      parsedCombo.repeat = false;
+    const lastCombo = parsedChord.at(-1);
+    if (binding.repeat === false && lastCombo) {
+      lastCombo.repeat = false;
    }
-    return { ...binding, combo: override, parsedCombo };
+    return { ...binding, combo: override, parsedChord };
  });
 }

@@ -921,6 +929,27 @@ function resolvePayload(
  }
 }

+const CHORD_TIMEOUT_MS = 1500;
+
+function clearChordTimeout(timeoutId: ReturnType<typeof setTimeout> | null): void {
+  if (timeoutId !== null) {
+    clearTimeout(timeoutId);
+  }
+}
+
+function createChordTimeout(onChordReset: () => void): ReturnType<typeof setTimeout> {
+  return setTimeout(onChordReset, CHORD_TIMEOUT_MS);
+}
+
+function resetChordState(input: ChordState): ChordState {
+  clearChordTimeout(input.timeoutId);
+  return {
+    candidateIndices: [],
+    step: 0,
+    timeoutId: null,
+  };
+}
+
 function helpMatchesPlatform(
  when: ShortcutWhen | undefined,
  context: KeyboardShortcutPlatformContext,
@@ -935,24 +964,131 @@ function helpMatchesPlatform(
 export function resolveKeyboardShortcut(input: {
  event: KeyboardEvent;
  context: KeyboardShortcutContext;
+  chordState: ChordState;
+  onChordReset: () => void;
  bindings?: readonly ParsedShortcutBinding[];
-}): KeyboardShortcutMatch | null {
-  const { event, context, bindings = DEFAULT_BINDINGS } = input;
-  for (const binding of bindings) {
-    if (!matchesCombo(binding.parsedCombo, event, context.isMac)) {
+}): {
+  match: KeyboardShortcutMatch | null;
+  nextChordState: ChordState;
+  preventDefault: boolean;
+};
+export function resolveKeyboardShortcut(input: {
+  event: KeyboardEvent;
+  context: KeyboardShortcutContext;
+  chordState: ChordState;
+  onChordReset: () => void;
+  bindings?: readonly ParsedShortcutBinding[];
+}): {
+  match: KeyboardShortcutMatch | null;
+  nextChordState: ChordState;
+  preventDefault: boolean;
+} {
+  const { event, context, chordState, onChordReset, bindings = DEFAULT_BINDINGS } = input;
+
+  if (chordState.step === 0) {
+    const advancingCandidateIndices: number[] = [];
+    let singleComboMatch: KeyboardShortcutMatch | null = null;
+
+    for (const [index, binding] of bindings.entries()) {
+      const firstCombo = binding.parsedChord[0];
+      if (!firstCombo) {
+        continue;
+      }
+      if (!matchesCombo(firstCombo, event, context.isMac)) {
+        continue;
+      }
+      if (!matchesWhen(binding.when, context)) {
+        continue;
+      }
+      if (binding.parsedChord.length > 1) {
+        advancingCandidateIndices.push(index);
+        continue;
+      }
+      if (!singleComboMatch) {
+        singleComboMatch = {
+          action: binding.action,
+          payload: resolvePayload(binding.payload, event),
+          preventDefault: binding.preventDefault ?? true,
+          stopPropagation: binding.stopPropagation ?? true,
+        };
+      }
+    }
+
+    if (advancingCandidateIndices.length > 0) {
+      return {
+        match: null,
+        nextChordState: {
+          candidateIndices: advancingCandidateIndices,
+          step: 1,
+          timeoutId: createChordTimeout(onChordReset),
+        },
+        preventDefault: true,
+      };
+    }
+
+    return {
+      match: singleComboMatch,
+      nextChordState: resetChordState(chordState),
+      preventDefault: false,
+    };
+  }
+
+  const matchingCandidateIndices: number[] = [];
+  let completedMatch: KeyboardShortcutMatch | null = null;
+
+  for (const index of chordState.candidateIndices) {
+    const binding = bindings[index];
+    if (!binding) {
+      continue;
+    }
+    const combo = binding.parsedChord[chordState.step];
+    if (!combo) {
+      continue;
+    }
+    if (!matchesCombo(combo, event, context.isMac)) {
      continue;
    }
    if (!matchesWhen(binding.when, context)) {
      continue;
    }
+    if (chordState.step + 1 === binding.parsedChord.length) {
+      completedMatch = {
+        action: binding.action,
+        payload: resolvePayload(binding.payload, event),
+        preventDefault: binding.preventDefault ?? true,
+        stopPropagation: binding.stopPropagation ?? true,
+      };
+      break;
+    }
+    matchingCandidateIndices.push(index);
+  }
+
+  if (completedMatch) {
    return {
-      action: binding.action,
-      payload: resolvePayload(binding.payload, event),
-      preventDefault: binding.preventDefault ?? true,
-      stopPropagation: binding.stopPropagation ?? true,
+      match: completedMatch,
+      nextChordState: resetChordState(chordState),
+      preventDefault: false,
    };
  }
-  return null;
+
+  if (matchingCandidateIndices.length > 0) {
+    clearChordTimeout(chordState.timeoutId);
+    return {
+      match: null,
+      nextChordState: {
+        candidateIndices: matchingCandidateIndices,
+        step: chordState.step + 1,
+        timeoutId: createChordTimeout(onChordReset),
+      },
+      preventDefault: true,
+    };
+  }
+
+  return {
+    match: null,
+    nextChordState: resetChordState(chordState),
+    preventDefault: false,
+  };
 }

 export function getBindingIdForAction(
--- a/packages/app/src/keyboard/shortcut-string.ts
+++ b/packages/app/src/keyboard/shortcut-string.ts
@@ -103,6 +103,10 @@ export function parseShortcutString(s: string): KeyCombo {
  return combo;
 }

+export function parseChordString(s: string): KeyCombo[] {
+  return s.split(" ").map(parseShortcutString);
+}
+
 export function keyComboToString(combo: KeyCombo): string {
  const parts: string[] = [];

@@ -122,6 +126,10 @@ export function keyComboToString(combo: KeyCombo): string {
  return parts.join("+");
 }

+export function chordToString(chord: KeyCombo[]): string {
+  return chord.map(keyComboToString).join(" ");
+}
+
 const MODIFIER_CODES = new Set([
  "MetaLeft",
  "MetaRight",
@@ -158,6 +166,10 @@ export function comboStringToShortcutKeys(comboString: string): ShortcutKey[] {
  return keys;
 }

+export function chordStringToShortcutKeys(s: string): ShortcutKey[][] {
+  return s.split(" ").map(comboStringToShortcutKeys);
+}
+
 export function keyboardEventToComboString(event: KeyboardEvent): string | null {
  if (MODIFIER_CODES.has(event.code)) {
    return null;
--- a/packages/app/src/screens/settings/keyboard-shortcuts-section.tsx
+++ b/packages/app/src/screens/settings/keyboard-shortcuts-section.tsx
@@ -10,16 +10,31 @@ import {
  getBindingIdForAction,
  type KeyboardShortcutHelpRow,
 } from "@/keyboard/keyboard-shortcuts";
-import { comboStringToShortcutKeys, keyboardEventToComboString } from "@/keyboard/shortcut-string";
+import {
+  chordStringToShortcutKeys,
+  comboStringToShortcutKeys,
+  keyboardEventToComboString,
+} from "@/keyboard/shortcut-string";
+import { useKeyboardShortcutsStore } from "@/stores/keyboard-shortcuts-store";
 import { getShortcutOs } from "@/utils/shortcut-platform";
 import { getIsDesktop } from "@/constants/layout";

+function ShortcutSequence({ chord }: { chord: string[] | null }) {
+  if (!chord || chord.length === 0) {
+    return <Text style={styles.capturingText}>Press shortcut...</Text>;
+  }
+
+  return <Shortcut chord={chord.map(comboStringToShortcutKeys)} />;
+}
+
 function ShortcutRow({
  row,
  bindingId,
  overrideCombo,
  isCapturing,
+  capturedCombos,
  onRebind,
+  onDone,
  onCancel,
  onReset,
 }: {
@@ -27,29 +42,38 @@ function ShortcutRow({
  bindingId: string | null;
  overrideCombo: string | undefined;
  isCapturing: boolean;
+  capturedCombos: string[];
  onRebind: () => void;
+  onDone: () => void;
  onCancel: () => void;
  onReset: () => void;
 }) {
-  const displayKeys = overrideCombo ? comboStringToShortcutKeys(overrideCombo) : row.keys;
+  const displayChord = overrideCombo ? chordStringToShortcutKeys(overrideCombo) : [row.keys];

  return (
    <View style={[styles.row, isCapturing && styles.rowCapturing]}>
      <Text style={styles.rowLabel}>{row.label}</Text>
      <View style={styles.rowActions}>
        {isCapturing ? (
-          <Text style={styles.capturingText}>Press shortcut...</Text>
+          <ShortcutSequence chord={capturedCombos} />
        ) : (
-          <Shortcut keys={displayKeys} />
+          <Shortcut chord={displayChord} />
        )}
        {bindingId !== null && (
-          <Button
-            variant="ghost"
-            size="sm"
-            onPress={isCapturing ? onCancel : onRebind}
-          >
-            {isCapturing ? "Cancel" : "Rebind"}
-          </Button>
+          <>
+            {isCapturing && capturedCombos.length > 0 ? (
+              <Button variant="ghost" size="sm" onPress={onDone}>
+                Done
+              </Button>
+            ) : null}
+            <Button
+              variant="ghost"
+              size="sm"
+              onPress={isCapturing ? onCancel : onRebind}
+            >
+              {isCapturing ? "Cancel" : "Rebind"}
+            </Button>
+          </>
        )}
        {overrideCombo !== undefined && !isCapturing && (
          <Button variant="ghost" size="sm" onPress={onReset}>
@@ -63,46 +87,73 @@ function ShortcutRow({

 export function KeyboardShortcutsSection() {
  const [capturingBindingId, setCapturingBindingId] = useState<string | null>(null);
+  const [capturedCombos, setCapturedCombos] = useState<string[]>([]);
  const { overrides, hasOverrides, setOverride, removeOverride, resetAll } =
    useKeyboardShortcutOverrides();
+  const setCapturingShortcut = useKeyboardShortcutsStore((s) => s.setCapturingShortcut);

  const isMac = getShortcutOs() === "mac";
  const isDesktop = getIsDesktop();
  const sections = buildKeyboardShortcutHelpSections({ isMac, isDesktop });

+  function cancelCapture() {
+    setCapturedCombos([]);
+    setCapturingBindingId(null);
+    setCapturingShortcut(false);
+  }
+
+  function startCapture(bindingId: string) {
+    setCapturedCombos([]);
+    setCapturingBindingId(bindingId);
+    setCapturingShortcut(true);
+  }
+
+  function saveCapture() {
+    if (capturingBindingId === null || capturedCombos.length === 0) {
+      return;
+    }
+    void setOverride(capturingBindingId, capturedCombos.join(" "));
+    cancelCapture();
+  }
+
  useEffect(() => {
    if (Platform.OS !== "web") return;
    if (capturingBindingId === null) return;

-    const activeBindingId = capturingBindingId;
-
    function handleKeyDown(event: KeyboardEvent) {
+      event.preventDefault();
+      event.stopPropagation();
+
      const key = event.key ?? "";
      if (key === "Escape") {
-        event.preventDefault();
-        event.stopPropagation();
-        setCapturingBindingId(null);
+        cancelCapture();
        return;
      }

-      if (key === "Alt" || key === "Control" || key === "Meta" || key === "Shift") {
+      if (key === "Backspace") {
+        setCapturedCombos((current) => (current.length > 0 ? current.slice(0, -1) : current));
        return;
      }

      const comboString = keyboardEventToComboString(event);
-      if (comboString === null) return;
+      if (comboString === null) {
+        return;
+      }

-      event.preventDefault();
-      event.stopPropagation();
-      void setOverride(activeBindingId, comboString);
-      setCapturingBindingId(null);
+      setCapturedCombos((current) => [...current, comboString]);
    }

    window.addEventListener("keydown", handleKeyDown, true);
    return () => {
      window.removeEventListener("keydown", handleKeyDown, true);
    };
-  }, [capturingBindingId, setOverride]);
+  }, [cancelCapture, capturingBindingId]);
+
+  useEffect(() => {
+    return () => {
+      setCapturingShortcut(false);
+    };
+  }, [setCapturingShortcut]);

  if (Platform.OS !== "web") {
    return (
@@ -144,8 +195,14 @@ export function KeyboardShortcutsSection() {
                      bindingId={bindingId}
                      overrideCombo={overrideCombo}
                      isCapturing={capturingBindingId === bindingId}
-                      onRebind={() => setCapturingBindingId(bindingId)}
-                      onCancel={() => setCapturingBindingId(null)}
+                      capturedCombos={capturingBindingId === bindingId ? capturedCombos : []}
+                      onRebind={() => {
+                        if (bindingId) {
+                          startCapture(bindingId);
+                        }
+                      }}
+                      onDone={saveCapture}
+                      onCancel={cancelCapture}
                      onReset={() => {
                        if (bindingId) void removeOverride(bindingId);
                      }}
--- a/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx
+++ b/packages/app/src/screens/workspace/workspace-desktop-tabs-row.tsx
@@ -457,7 +457,7 @@ export function WorkspaceDesktopTabsRow({
            <View style={styles.newTabTooltipRow}>
              <Text style={styles.newTabTooltipText}>New agent tab</Text>
              {newAgentTabKeys ? (
-                <Shortcut keys={newAgentTabKeys} style={styles.newTabTooltipShortcut} />
+                <Shortcut chord={newAgentTabKeys} style={styles.newTabTooltipShortcut} />
              ) : null}
            </View>
          </TooltipContent>
@@ -478,7 +478,7 @@ export function WorkspaceDesktopTabsRow({
            <View style={styles.newTabTooltipRow}>
              <Text style={styles.newTabTooltipText}>New terminal tab</Text>
              {newTerminalTabKeys ? (
-                <Shortcut keys={newTerminalTabKeys} style={styles.newTabTooltipShortcut} />
+                <Shortcut chord={newTerminalTabKeys} style={styles.newTabTooltipShortcut} />
              ) : null}
            </View>
          </TooltipContent>
@@ -499,7 +499,7 @@ export function WorkspaceDesktopTabsRow({
            <View style={styles.newTabTooltipRow}>
              <Text style={styles.newTabTooltipText}>Split pane right</Text>
              {splitRightKeys ? (
-                <Shortcut keys={splitRightKeys} style={styles.newTabTooltipShortcut} />
+                <Shortcut chord={splitRightKeys} style={styles.newTabTooltipShortcut} />
              ) : null}
            </View>
          </TooltipContent>
@@ -520,7 +520,7 @@ export function WorkspaceDesktopTabsRow({
            <View style={styles.newTabTooltipRow}>
              <Text style={styles.newTabTooltipText}>Split pane down</Text>
              {splitDownKeys ? (
-                <Shortcut keys={splitDownKeys} style={styles.newTabTooltipShortcut} />
+                <Shortcut chord={splitDownKeys} style={styles.newTabTooltipShortcut} />
              ) : null}
            </View>
          </TooltipContent>
--- a/packages/app/src/stores/keyboard-shortcuts-store.test.ts
+++ b/packages/app/src/stores/keyboard-shortcuts-store.test.ts
@@ -4,7 +4,9 @@ import { useKeyboardShortcutsStore } from "./keyboard-shortcuts-store";
 beforeEach(() => {
  useKeyboardShortcutsStore.setState({
    commandCenterOpen: false,
+    projectPickerOpen: false,
    shortcutsDialogOpen: false,
+    capturingShortcut: false,
    altDown: false,
    cmdOrCtrlDown: false,
    sidebarShortcutWorkspaceTargets: [],
@@ -18,4 +20,10 @@ describe("keyboard-shortcuts-store", () => {
    useKeyboardShortcutsStore.getState().setCommandCenterOpen(true);
    expect(useKeyboardShortcutsStore.getState().commandCenterOpen).toBe(true);
  });
+
+  it("toggles shortcut capture state", () => {
+    expect(useKeyboardShortcutsStore.getState().capturingShortcut).toBe(false);
+    useKeyboardShortcutsStore.getState().setCapturingShortcut(true);
+    expect(useKeyboardShortcutsStore.getState().capturingShortcut).toBe(true);
+  });
 });
--- a/packages/app/src/stores/keyboard-shortcuts-store.ts
+++ b/packages/app/src/stores/keyboard-shortcuts-store.ts
@@ -5,6 +5,7 @@ interface KeyboardShortcutsState {
  commandCenterOpen: boolean;
  projectPickerOpen: boolean;
  shortcutsDialogOpen: boolean;
+  capturingShortcut: boolean;
  altDown: boolean;
  cmdOrCtrlDown: boolean;
  /** Sidebar-visible workspace targets (up to 9), in top-to-bottom visual order. */
@@ -15,6 +16,7 @@ interface KeyboardShortcutsState {
  setCommandCenterOpen: (open: boolean) => void;
  setProjectPickerOpen: (open: boolean) => void;
  setShortcutsDialogOpen: (open: boolean) => void;
+  setCapturingShortcut: (capturing: boolean) => void;
  setAltDown: (down: boolean) => void;
  setCmdOrCtrlDown: (down: boolean) => void;
  setSidebarShortcutWorkspaceTargets: (targets: SidebarShortcutWorkspaceTarget[]) => void;
@@ -26,6 +28,7 @@ export const useKeyboardShortcutsStore = create<KeyboardShortcutsState>((set) =>
  commandCenterOpen: false,
  projectPickerOpen: false,
  shortcutsDialogOpen: false,
+  capturingShortcut: false,
  altDown: false,
  cmdOrCtrlDown: false,
  sidebarShortcutWorkspaceTargets: [],
@@ -34,6 +37,7 @@ export const useKeyboardShortcutsStore = create<KeyboardShortcutsState>((set) =>
  setCommandCenterOpen: (open) => set({ commandCenterOpen: open }),
  setProjectPickerOpen: (open) => set({ projectPickerOpen: open }),
  setShortcutsDialogOpen: (open) => set({ shortcutsDialogOpen: open }),
+  setCapturingShortcut: (capturing) => set({ capturingShortcut: capturing }),
  setAltDown: (down) => set({ altDown: down }),
  setCmdOrCtrlDown: (down) => set({ cmdOrCtrlDown: down }),
  setSidebarShortcutWorkspaceTargets: (targets) =>