Repository navigation
feat: add a few high-value keyboard shortcuts + shortcut cheat-sheet/tooltips #64
Description
Motivation< CFD2 /h2>
wmux already ships a strong, remappable shortcut set (38 actions, listed in the Ctrl+Shift+P command palette, editable in Settings → Keyboard) — all the workspace/tab/split basics are done. This issue proposes a small set of high-productivity shortcuts that are still missing vs cmux, plus a discoverability feature. Kept intentionally focused to avoid bloating the shortcut surface.
Already covered (no work needed)
| Capability | wmux action | wmux default | cmux equivalent |
|---|---|---|---|
| New workspace | newWorkspace |
Ctrl+N |
⌘N |
| Switch workspace (cycle / index) | nextWorkspace / prevWorkspace / built-in |
Ctrl+PgDn / Ctrl+PgUp / Ctrl+1…9 |
⌃⌘] / ⌃⌘[ / ⌘1…9 |
| Jump to workspace with unread notification | jumpToUnread |
Ctrl+Shift+U |
⌘⇧U |
| Rename workspace | renameWorkspace |
Ctrl+Shift+F2 |
⌘⇧R |
| New terminal tab | newSurface |
Ctrl+T |
⌘T |
| Next / previous tab | nextSurface / prevSurface |
Ctrl+Shift+] / Ctrl+Shift+[ |
⌘⇧] / ⌘⇧[ |
| Split right / down | splitRight / splitDown |
Ctrl+D / Ctrl+Shift+D |
⌘D / ⌘⇧D |
The five shortcuts originally requested (new workspace, switch workspace, switch-to-notification, new tab, split) are all in this table — so this issue only adds genuinely new, high-value actions.
Proposed additions (high-value only)
Suggested Windows defaults are collision-checked against current defaults and remappable.
| Proposed action | What it does | Why it's worth it | Suggested default | cmux |
|---|---|---|---|---|
selectSurface1…9 |
Jump straight to tab N in the focused pane | Fast tab switching when juggling several agents/shells | Ctrl+Alt+1…9 |
⌃1–9 |
reopenClosedSurface |
Restore the last-closed tab | Universal "oops, brought it back" muscle memory | Ctrl+Shift+T |
⌘⇧T |
findNext / findPrevious |
Cycle search matches without reopening the find bar | Core search ergonomics; currently no next/prev | F3 / Shift+F3 |
⌘G / ⌥⌘G |
resizePaneLeft/Right/Up/Down |
Grow/shrink the focused pane from the keyboard | Daily layout tuning; also sidesteps the mouse-resize pains in #57/#59 | Ctrl+Shift+Arrows |
— |
broadcastInput |
Toggle: typed input + Enter go to all panes in the workspace | wmux's "for AI agents" superpower — drive several Claude Code panes at once (tmux synchronize-panes) |
Ctrl+Alt+B |
— |
Plus one fix, not a new binding: openFolder (Ctrl+O) is already bound but a no-op stub (useKeyboardShortcuts.ts: "needs OS file dialog via IPC, not yet implemented"). Wire it to a folder picker that opens a workspace there.
Workspace actions (act on the active workspace)
These already exist in the sidebar right-click menu (WorkspaceContextMenu.tsx) but have no keyboard equivalent. Each is a one-liner (onUpdateMetadata(active, …) in Sidebar.tsx), targeting the currently active workspace.
| Proposed action | What it does | Why it's worth it | Suggested default |
|---|---|---|---|
togglePinWorkspace |
Pin / unpin the active workspace | Keep important workspaces at the top without reaching for the mouse | Ctrl+Alt+P |
markWorkspaceRead |
Clear the unread badge on the active workspace | Quickly dismiss the "needs attention" marker after checking a pane | Ctrl+Alt+R |
Rename is intentionally not listed here — it already has a shortcut (
renameWorkspace,Ctrl+Shift+F2).markWorkspaceUnreadcould be added too for symmetry, butmarkWorkspaceReadis the high-value one.
Discoverability — cheat-sheet overlay + tooltips
Bindings are currently discoverable only by searching the command palette or digging into Settings. Two small additions teach them in-context (cmux surfaces shortcuts this way):
- Shortcut cheat-sheet overlay — a toggleable, search-filterable overlay (suggested
F1orCtrl+/) listing every action grouped by category with its current binding. Reuses the existingformatBinding()helper and the sameshortcutsmap, so it stays in sync with user remaps. - Inline hover tooltips — show the binding on hover over the control that triggers it (new-tab
+, split buttons, zoom, sidebar rows), e.g. "New tab — Ctrl+T".
Implementation pointers
- Add each action to the
ShortcutActionunion +DEFAULT_SHORTCUTS(src/renderer/store/settings-slice.ts). - Add a
caseindispatchAction()(useKeyboardShortcuts.ts); reusesplit-utils.tshelpers and existing store actions (addSurface,selectSurface, …). - Command palette + Keyboard settings pick up new actions automatically (they iterate
Object.entries(shortcuts)). reopenClosedSurfaceneeds a small "recently closed" stack in the surface slice.- For any new bare-
Ctrlcombo, updateSAFE_CTRL_KEYS/isSafeToIntercept().
Acceptance criteria
-
selectSurface1…9,reopenClosedSurface -
findNext/findPrevious - keyboard pane resize (
resizePane*) -
broadcastInput -
togglePinWorkspace,markWorkspaceRead(active workspace) -
openFolderno longer a no-op - cheat-sheet overlay + inline tooltips
- all new actions appear in the palette and are remappable in Settings → Keyboard
Activity
feat(#64,#63): keyboard shortcuts + cheat-sheet; fix diff-tab workspa…
amirlehmam commentedon Jun 28, 2026
Shipped in v0.13.0 (commit 7432593). Walking the acceptance criteria:
reopenClosedSurface—Ctrl+Shift+T. Backed by a small reopen stack insurface-slice.ts; restores tab metadata (type / title / shell / cwd / url / startup commands). The terminal restarts fresh since its PTY is gone.findNext/findPrevious—F3/Shift+F3. Dispatched to the focused, visible terminal'sSearchAddon, cycling the last query without reopening the find bar.resizePane{Left,Right,Up,Down}onCtrl+Shift+Arrows. NewadjustPaneRatio()helper nudges the nearest enclosing divider (move-divider semantics, like tmuxresize-pane), clamped to 10–90%.broadcastInput—Ctrl+Alt+B. Toggles fanning your keystrokes to each pane's visible terminal in the workspace (background keep-alive tabs are intentionally skipped). A red banner shows while it's active. Runtime-only — deliberately not persisted, so a dangerous mode never silently restores on launch.togglePinWorkspace(Ctrl+Alt+P) andmarkWorkspaceRead(Ctrl+Alt+R) on the active workspace.openFolder—Ctrl+Ois no longer a no-op. Newsystem:pickFolderIPC handler shows a native directory dialog; the chosen folder opens as a new workspace rooted there.F1, searchable, grouped by category, and it renders your live bindings (so remaps show up immediately). Plus inline tooltips on the tab-bar controls (new-tab, split, close) now show their current binding.ShortcutActionunion +DEFAULT_SHORTCUTS, so the command palette and Settings → Keyboard pick them up automatically.One implementation note on
selectSurface1…9: I shipped it as a fixedCtrl+Alt+1…9handler that mirrors the existingCtrl+1…9workspace-index selector, rather than nine individually-remappable entries — nine extra rows would have bloated the Settings → Keyboard list considerably for a low-collision binding. It's listed in the cheat-sheet under Tabs. Happy to make them remappable if you'd rather.While wiring this up I also refactored the keyboard dispatch from a 35-case
switchinto a handler table, and fixed a latent bug whereaddSurfacereturned a freshly-minted id even when the target pane no longer existed (now returnsnull).Defaults were collision-checked against the existing set and all remain remappable. Release: https://github.com/amirlehmam/wmux/releases/tag/v0.13.0
fix(terminal): route Shift+Enter newline through terminal.input for b…