The best way to control Claude Code, Codex and more from any computer or phone
feat(web): unassign default keyboard shortcuts (#28687)
Co-authored-by: maria-rcks <maria@kuuro.net> Co-authored-by: Julius Marminge <julius0216@outlook.com>
Lukas Böhm committed
Nov 17, 2026 at 07:26 UTC
d27002bf99358509a864793ee8d25117a7f39756
7 files changed
+215
-28
apps/server/src/keybindings.test.ts
+47
@@ -446,6 +446,53 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
446
}).pipe(Effect.provide(layerKeybindings())),
447
);
448
449
+ it.effect("unassigns a shortcut without restoring it on startup and can reassign it", () =>
450
+ Effect.gen(function* () {
451
+ const { keybindingsConfigPath } = yield* ServerConfig.ServerConfig;
452
+ yield* writeKeybindingsConfig(
453
+ keybindingsConfigPath,
454
+ Array.from({ length: MAX_KEYBINDINGS_COUNT }, (_, index) => ({
455
+ key: "mod+alt+f1",
456
+ command: `script.filler-${index}.run` as const,
457
+ })),
458
+ );
459
+ const keybindings = yield* Keybindings.Keybindings;
460
+ const target = SharedKeybindings.DEFAULT_KEYBINDINGS.find(
461
+ (rule) => rule.command === "composer.sendBackground",
462
+ )!;
463
+ const siblings = SharedKeybindings.DEFAULT_KEYBINDINGS.filter(
464
+ (rule) => rule.command === target.command && rule !== target,
465
+ );
466
+ const removed = yield* keybindings.upsertKeybindingRule({
467
+ ...target,
468
+ when: "false",
469
+ replace: target,
470
+ });
471
+ const expected = SharedKeybindings.compileResolvedKeybindingsConfig([
472
+ ...siblings,
473
+ { ...target, when: "false" },
474
+ ]);
475
+ assert.deepEqual(
476
+ removed.keybindings.filter((rule) => rule.command === target.command),
477
+ expected,
478
+ );
479
+ yield* keybindings.syncDefaultKeybindingsOnStartup;
480
+ const snapshot = yield* keybindings.getSnapshot;
481
+ assert.deepEqual(
482
+ snapshot.keybindings.filter((rule) => rule.command === target.command),
483
+ expected,
484
+ );
485
+ const restored = yield* keybindings.upsertKeybindingRule({
486
+ ...target,
487
+ replace: { ...target, when: "false" },
488
+ });
489
+ assert.deepEqual(
490
+ restored.keybindings.filter((rule) => rule.command === target.command),
491
+ SharedKeybindings.compileResolvedKeybindingsConfig([...siblings, target]),
492
+ );
493
+ }).pipe(Effect.provide(layerKeybindings())),
494
+ );
495
+
496
it.effect("keeps entries it cannot decode when editing other keybindings", () =>
497
Effect.gen(function* () {
498
const fs = yield* FileSystem.FileSystem;
apps/server/src/keybindings.ts
+26
-16
@@ -529,7 +529,11 @@ const make = Effect.gen(function* () {
529
for (const { alongside, rule } of pendingLateDefaults) {
530
if (
531
customConfig.some((entry) => isSameKeybindingRule(entry, alongside)) &&
532
- !customConfig.some((entry) => hasSameShortcutContext(entry, rule))
532
+ !customConfig.some(
533
+ (entry) =>
534
+ hasSameShortcutContext(entry, rule) ||
535
+ isSameKeybindingRule(entry, { ...rule, when: "false" }),
536
+ )
537
) {
538
missingDefaults.push(rule);
539
}
@@ -665,29 +669,35 @@ const make = Effect.gen(function* () {
669
const customConfig = yield* loadWritableCustomKeybindingsConfig();
670
const rule = keybindingRuleFromInput(input);
671
const replaceTarget = replaceTargetFromUpsertInput(input);
672
+ const siblingDefaults =
673
+ rule.when === "false" &&
674
+ replaceTarget &&
675
+ !customConfig.some(({ rule: entry }) => entry?.command === rule.command)
676
+ ? DEFAULT_KEYBINDINGS.filter(
677
+ (entry) =>
678
+ entry.command === rule.command && !isSameKeybindingRule(entry, replaceTarget),
679
+ ).map((entry) => ({ value: entry, rule: entry }))
680
+ : [];
681
+ const retainedConfig = customConfig.filter(({ rule: entry }) => {
682
+ if (!entry) return true;
683
+ return (
684
+ (!replaceTarget || !isSameKeybindingRule(entry, replaceTarget)) &&
685
+ !isSameKeybindingRule(entry, rule)
686
+ );
687
+ });
688
+ const availableSlots = MAX_KEYBINDINGS_COUNT - siblingDefaults.length - 1;
689
const nextConfig = [
669
- ...customConfig.filter(({ rule: entry }) => {
670
- if (!entry) return true;
671
- if (replaceTarget) {
672
- return (
673
- !isSameKeybindingRule(entry, replaceTarget) && !isSameKeybindingRule(entry, rule)
674
- );
675
- }
676
- return !isSameKeybindingRule(entry, rule);
677
- }),
690
+ ...siblingDefaults,
691
+ ...retainedConfig.slice(-availableSlots),
692
{ value: rule, rule },
693
];
680
- const cappedConfig =
681
- nextConfig.length > MAX_KEYBINDINGS_COUNT
682
- ? nextConfig.slice(-MAX_KEYBINDINGS_COUNT)
683
- : nextConfig;
684
- if (nextConfig.length > MAX_KEYBINDINGS_COUNT) {
694
+ if (retainedConfig.length > availableSlots) {
695
yield* Effect.logWarning("truncating keybindings config to max entries", {
696
path: keybindingsConfigPath,
697
maxEntries: MAX_KEYBINDINGS_COUNT,
698
});
699
}
690
- yield* writeConfigAtomically(cappedConfig.map(({ value }) => value));
700
+ yield* writeConfigAtomically(nextConfig.map(({ value }) => value));
701
return yield* reloadAndEmit;
702
}),
703
),
apps/web/src/components/settings/KeybindingsSettings.browser.test.tsx
+54
-2
@@ -3,6 +3,8 @@ import { describe, expect, it, vi } from "vite-plus/test";
3
import { page, userEvent, type Locator } from "vite-plus/test/browser";
4
5
import { render } from "../../../test/render";
6
+import { compileResolvedKeybindingsConfig } from "@t3tools/shared/keybindings";
7
+import * as atomCommands from "../../state/use-atom-command";
8
9
vi.mock(import("../../state/session"), async (original) => ({
10
...(await original()),
@@ -13,7 +15,7 @@ vi.mock(import("../../state/session"), async (original) => ({
15
}));
16
vi.mock(import("../../state/use-atom-command"), async (original) => ({
17
...(await original()),
16
- useAtomCommand: (() => vi.fn()) as never,
18
+ useAtomCommand: vi.fn(() => vi.fn()) as never,
19
}));
20
vi.mock(import("./SettingsScopeContext"), async (original) => ({
21
...(await original()),
@@ -21,7 +23,13 @@ vi.mock(import("./SettingsScopeContext"), async (original) => ({
23
const environment = {
24
environmentId: "env",
25
label: "Build workstation",
24
- serverConfig: { keybindings: [], keybindingsConfigPath: null, availableEditors: [] },
26
+ serverConfig: {
27
+ keybindings: compileResolvedKeybindingsConfig([
28
+ { command: "composer.sendBackground", key: "mod+alt+enter", when: "false" },
29
+ ]),
30
+ keybindingsConfigPath: null,
31
+ availableEditors: [],
32
+ },
33
};
34
return {
35
scope: { kind: "environment" },
@@ -105,6 +113,50 @@ describe("Esc in a shortcut recorder", () => {
113
});
114
});
115
116
+it("unassigns a default shortcut and restores its condition when one is assigned again", async () => {
117
+ const mutate = vi.fn(async () => ({ _tag: "Success", value: [] }));
118
+ await vi.mocked(atomCommands.useAtomCommand).withImplementation(
119
+ () => mutate as never,
120
+ async () => {
121
+ await using screen = await render(<KeybindingsSettingsPanel />);
122
+
123
+ await screen.getByRole("button", { name: "Actions for Sidebar: Toggle" }).click();
124
+ await screen.getByRole("menuitem", { name: "Unassign" }).click();
125
+ expect(mutate).toHaveBeenLastCalledWith({
126
+ environmentId: "env",
127
+ input: {
128
+ command: "sidebar.toggle",
129
+ key: "mod+b",
130
+ when: "false",
131
+ replace: { command: "sidebar.toggle", key: "mod+b" },
132
+ },
133
+ });
134
+
135
+ const unassigned = screen.getByRole("button", {
136
+ name: "Edit shortcut for Composer: Start in Background: Unassigned",
137
+ });
138
+ const save = screen.getByRole("button", { name: "Save" });
139
+ await unassigned.click();
140
+ await userEvent.keyboard("{Control>}{Alt>}j{/Alt}{/Control}");
141
+ await expect.element(save).toBeVisible();
142
+ await userEvent.keyboard("{Escape}");
143
+ await expect.element(save).not.toBeInTheDocument();
144
+
145
+ await unassigned.click();
146
+ await userEvent.keyboard("{Control>}{Alt>}j{/Alt}{/Control}");
147
+ await save.click();
148
+ expect(mutate).toHaveBeenLastCalledWith({
149
+ environmentId: "env",
150
+ input: expect.objectContaining({
151
+ command: "composer.sendBackground",
152
+ when: "composerFocus && draftThreadRoute",
153
+ replace: { command: "composer.sendBackground", key: "mod+alt+enter", when: "false" },
154
+ }),
155
+ });
156
+ },
157
+ );
158
+});
159
+
160
it("Esc in the keybindings search clears the query without closing Settings", async () => {
161
const onOpenChange = vi.fn();
162
await using _screen = await render(
apps/web/src/components/settings/KeybindingsSettings.logic.test.ts
+6
@@ -264,6 +264,12 @@ describe("KeybindingsSettings.logic", () => {
264
] satisfies ResolvedKeybindingsConfig);
265
266
expect(rows[0]?.conflicts).toEqual(["Chat: New Local"]);
267
+ const disabledRows = buildKeybindingRows([
268
+ rows[0]!.binding,
269
+ { ...rows[1]!.binding, whenAst: { type: "identifier", name: "false" } },
270
+ ]);
271
+ expect(disabledRows.map((row) => row.conflicts)).toEqual([[], []]);
272
+
273
expect(
274
keybindingConflictLabels(rows, {
275
rowId: rows[0]?.id ?? "",
apps/web/src/components/settings/KeybindingsSettings.logic.ts
+13
@@ -48,6 +48,7 @@ export interface KeybindingRow {
48
readonly key: string;
49
readonly when: string;
50
readonly source: KeybindingSource;
51
+ readonly isUnassigned: boolean;
52
readonly defaultKey: string | null;
53
readonly defaultWhen: string;
54
readonly binding: ResolvedKeybindingRule;
@@ -163,6 +164,13 @@ function defaultBindingForBinding(
164
shortcutToKeybindingInput(entry.shortcut) === bindingKey &&
165
whenAstToExpression(entry.whenAst) === bindingWhen,
166
) ??
167
+ (bindingWhen === "false"
168
+ ? DEFAULT_RESOLVED_KEYBINDINGS.find(
169
+ (entry) =>
170
+ entry.command === binding.command &&
171
+ shortcutToKeybindingInput(entry.shortcut) === bindingKey,
172
+ )
173
+ : undefined) ??
174
DEFAULT_RESOLVED_KEYBINDINGS.find(
175
(entry) =>
176
entry.command === binding.command && whenAstToExpression(entry.whenAst) === bindingWhen,
@@ -176,6 +184,7 @@ function keybindingRowId(command: KeybindingCommand, key: string, when: string):
184
}
185
186
function conflictsWithWhen(leftWhen: string, rightWhen: string): boolean {
187
+ if (leftWhen === "false" || rightWhen === "false") return false;
188
return leftWhen.length === 0 || rightWhen.length === 0 || leftWhen === rightWhen;
189
}
190
@@ -263,6 +272,10 @@ export function buildKeybindingRows(
272
key,
273
when,
274
source: sourceForBinding(binding),
275
+ isUnassigned:
276
+ when === "false" &&
277
+ defaultBinding !== undefined &&
278
+ key === shortcutToKeybindingInput(defaultBinding.shortcut),
279
defaultKey: defaultBinding ? shortcutToKeybindingInput(defaultBinding.shortcut) : null,
280
defaultWhen: whenAstToExpression(defaultBinding?.whenAst),
281
binding,
apps/web/src/components/settings/KeybindingsSettings.tsx
+66
-10
@@ -29,7 +29,10 @@ import {
29
type ServerRemoveKeybindingInput,
30
type ServerUpsertKeybindingInput,
31
} from "@t3tools/contracts";
32
-import { mergeWithDefaultKeybindings } from "@t3tools/shared/keybindings";
32
+import {
33
+ mergeWithDefaultKeybindings,
34
+ parseKeybindingWhenExpression,
35
+} from "@t3tools/shared/keybindings";
36
import {
37
isAtomCommandInterrupted,
38
squashAtomCommandFailure,
@@ -730,6 +733,16 @@ function useKeybindingRowEditor({
733
when: whenDraftExpression,
734
});
735
736
+ // Giving an unassigned row a shortcut brings back its default condition.
737
+ const setKeyDraft = (next: string, patch: Partial<KeybindingRowDraftState> = {}) =>
738
+ setDraft({
739
+ ...patch,
740
+ keyDraft: next,
741
+ ...(row.isUnassigned && whenDraftExpression === "false"
742
+ ? { whenDraft: parseKeybindingWhenExpression(row.defaultWhen) ?? undefined }
743
+ : {}),
744
+ });
745
+
746
const save = () => {
747
onSave({
748
command: row.command,
@@ -746,7 +759,15 @@ function useKeybindingRowEditor({
759
// An unhandled Escape closes the settings page.
760
event.stopPropagation();
761
const field = event.currentTarget;
749
- flushSync(() => setDraft({ keyDraft: row.key, isRecording: false }));
762
+ flushSync(() =>
763
+ setDraft({
764
+ keyDraft: row.key,
765
+ isRecording: false,
766
+ ...(row.isUnassigned && whenDraftExpression === row.defaultWhen
767
+ ? { whenDraft: parseKeybindingWhenExpression(row.when) ?? undefined }
768
+ : {}),
769
+ }),
770
+ );
771
// The field may unmount for the pill; focus would otherwise drop to the page.
772
if (pillRef.current) pillRef.current.focus();
773
else field.blur();
@@ -756,7 +777,7 @@ function useKeybindingRowEditor({
777
layoutCharacter: true,
778
});
779
if (!next) return;
759
- setDraft({ keyDraft: next, isRecording: false });
780
+ setKeyDraft(next, { isRecording: false });
781
};
782
783
return {
@@ -768,6 +789,7 @@ function useKeybindingRowEditor({
789
isDirty,
790
conflictLabels,
791
setDraft,
792
+ setKeyDraft,
793
save,
794
captureKeybinding,
795
pillRef,
@@ -781,6 +803,7 @@ interface KeybindingRowActions {
803
variables: ReadonlyArray<WhenVariableOption>;
804
onSave: (input: ServerUpsertKeybindingInput) => void;
805
onReset: (row: KeybindingRow) => void;
806
+ onUnassign: (row: KeybindingRow) => void;
807
onRemove: (row: KeybindingRow) => void;
808
}
809
@@ -807,6 +830,7 @@ function KeybindingKeyControl({
830
isDirty,
831
isWhenDraftValid,
832
setDraft,
833
+ setKeyDraft,
834
save,
835
captureKeybinding,
836
pillRef,
@@ -829,13 +853,17 @@ function KeybindingKeyControl({
853
ref={pillRef}
854
type="button"
855
onClick={() => setDraft({ isRecording: true })}
832
- aria-label={`Edit shortcut for ${commandLabel(row.command)}: ${formatShortcutLabel(row.binding.shortcut)}`}
856
+ aria-label={`Edit shortcut for ${commandLabel(row.command)}: ${row.isUnassigned ? "Unassigned" : formatShortcutLabel(row.binding.shortcut)}`}
857
className={cn(
858
"inline-flex h-8 cursor-pointer items-center rounded-md border border-transparent px-1.5 sm:h-7 outline-none transition-colors hover:border-border/70 hover:bg-accent focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-inset focus-visible:ring-ring/24",
859
pillClassName,
860
)}
861
>
838
- <KeybindingPill value={row.key} />
862
+ {row.isUnassigned ? (
863
+ <span className="text-sm text-muted-foreground">Unassigned</span>
864
+ ) : (
865
+ <KeybindingPill value={row.key} />
866
+ )}
867
</button>
868
) : (
869
<Input
@@ -849,7 +877,7 @@ function KeybindingKeyControl({
877
className="w-44"
878
onFocus={() => setDraft({ isRecording: true })}
879
onBlur={() => setDraft({ isRecording: false })}
852
- onChange={(event) => setDraft({ keyDraft: event.currentTarget.value })}
880
+ onChange={(event) => setKeyDraft(event.currentTarget.value)}
881
onKeyDown={captureKeybinding}
882
/>
883
)}
@@ -908,16 +936,19 @@ function KeybindingRowMenu({
936
row,
937
isSaving,
938
onReset,
939
+ onUnassign,
940
onRemove,
941
}: {
942
row: KeybindingRow;
943
isSaving: boolean;
944
onReset: (row: KeybindingRow) => void;
945
+ onUnassign: (row: KeybindingRow) => void;
946
onRemove: (row: KeybindingRow) => void;
947
}) {
948
const canReset = row.source === "Custom" && row.defaultKey !== null;
919
- const canRemove = row.source !== "Default";
920
- if (!canReset && !canRemove) return null;
949
+ const canUnassign = row.source === "Default";
950
+ // Reset to default is the way back; removing would drop the default for good.
951
+ const canRemove = row.source !== "Default" && !row.isUnassigned;
952
953
return (
954
<Menu>
@@ -940,6 +971,11 @@ function KeybindingRowMenu({
971
Reset to default
972
</MenuItem>
973
) : null}
974
+ {canUnassign ? (
975
+ <MenuItem variant="destructive" disabled={isSaving} onClick={() => onUnassign(row)}>
976
+ Unassign
977
+ </MenuItem>
978
+ ) : null}
979
{canRemove ? (
980
<MenuItem variant="destructive" disabled={isSaving} onClick={() => onRemove(row)}>
981
Remove
@@ -999,6 +1035,7 @@ function KeybindingHoverRowMenu(props: {
1035
row: KeybindingRow;
1036
isSaving: boolean;
1037
onReset: (row: KeybindingRow) => void;
1038
+ onUnassign: (row: KeybindingRow) => void;
1039
onRemove: (row: KeybindingRow) => void;
1040
}) {
1041
return (
@@ -1009,7 +1046,8 @@ function KeybindingHoverRowMenu(props: {
1046
}
1047
1048
function KeybindingSettingsRow(props: KeybindingRowProps) {
1012
- const { row, isSaving, anchorId, allRows, variables, onSave, onReset, onRemove } = props;
1049
+ const { row, isSaving, anchorId, allRows, variables, onSave, onReset, onUnassign, onRemove } =
1050
+ props;
1051
const editor = useKeybindingRowEditor({ row, allRows, onSave });
1052
1053
return (
@@ -1017,7 +1055,13 @@ function KeybindingSettingsRow(props: KeybindingRowProps) {
1055
id={anchorId}
1056
className="group/row rounded-none"
1057
title={<KeybindingRowTitle row={row} />}
1020
- description={<KeybindingRowWhen row={row} editor={editor} variables={variables} />}
1058
+ description={
1059
+ row.isUnassigned && !editor.isDirty ? (
1060
+ "No keyboard shortcut assigned. Click Unassigned to set one."
1061
+ ) : (
1062
+ <KeybindingRowWhen row={row} editor={editor} variables={variables} />
1063
+ )
1064
+ }
1065
control={
1066
<div className="flex flex-wrap items-center justify-end gap-1.5">
1067
<KeybindingConflictWarning labels={editor.conflictLabels} />
@@ -1025,6 +1069,7 @@ function KeybindingSettingsRow(props: KeybindingRowProps) {
1069
row={row}
1070
isSaving={isSaving}
1071
onReset={onReset}
1072
+ onUnassign={onUnassign}
1073
onRemove={onRemove}
1074
/>
1075
<KeybindingKeyControl
@@ -1444,6 +1489,16 @@ export function KeybindingsSettingsPanel() {
1489
})();
1490
};
1491
1492
+ const unassignKeybinding = (row: KeybindingRow) => {
1493
+ if (row.source !== "Default") return;
1494
+ saveKeybinding({
1495
+ command: row.command,
1496
+ key: row.key,
1497
+ when: "false",
1498
+ replace: rowKeybindingTarget(row),
1499
+ });
1500
+ };
1501
+
1502
const resetKeybinding = (row: KeybindingRow) => {
1503
if (!row.defaultKey) return;
1504
saveKeybinding({
@@ -1465,6 +1520,7 @@ export function KeybindingsSettingsPanel() {
1520
variables: whenVariables,
1521
onSave: saveKeybinding,
1522
onReset: resetKeybinding,
1523
+ onUnassign: unassignKeybinding,
1524
onRemove: removeKeybinding,
1525
};
1526
docs/user/keybindings.md
+3
@@ -3,6 +3,9 @@
3
Customize shortcuts in **Settings → Keybindings** on web and desktop. That page
4
also lists the command IDs and defaults available in your version.
5
6
+To free a default shortcut for another command, choose **Unassign** from its row's
7
+actions menu. **Reset to default** brings it back.
8
+
9
## Composer controls
10
11
`mod+shift+d` starts dictation in the focused editor, or the composer, and finishes it on the next press;