Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
/**
* The ⌘/ keyboard-shortcuts reference, DERIVED FROM THE REGISTRY.
*
* Every command row is produced by iterating `COMMAND_DEFINITIONS` — one section per
* `CommandGroup` in registry source order, one row per command, the label from `def.title` and
* EVERY one of the command's EFFECTIVE chords (`effectiveBindings` — the user's override when
* there is one). Nothing here enumerates command ids by hand, so a command added to the
* registry appears in this panel on the same commit, and one that is renamed cannot keep an old
* label here. That is the whole point: the previous version listed 24 ids by hand against a
* 45-command registry, so ⌘⇧T (reopen last closed), ⌘⇧↵ (maximize node), the ⌃⌥arrow zone snaps
* and Copy terminal selection were all live chords the panel never mentioned, and every
* ships-unbound command stayed invisible even after the user assigned it a chord.
* `ShortcutsPanel.test.tsx` is the watchdog (a new registry command that fails to show up reds it).
*
* **Unbound and user-disabled commands are omitted**, not listed as "none": the panel answers
* "which keys do things", and a row with no chord answers nothing. Settings → Keyboard Shortcuts
* is the surface that shows the whole pool, which is what the footer link points at.
*
* **Rows that are NOT registry commands** live in `extraRows` / `behaviorRows`: mouse gestures,
* the two zoom chords (`lib/zoomShortcut.ts`), the ⌘1-9 project jump (`lib/projectJump.ts`) and
* the terminal's own behaviors. They are literal because the registry does not know them — but
* they are still DERIVED from settings wherever the behavior is: the hover dwell prints
* `settings.panHoverDelay` (or "Click" when `settings.terminalFocusFollowsPointer` is off, #757),
* and the drag rows follow `settings.canvasDragMode`, because the panel
* used to claim a fixed 0.6 s and a right-drag pan that React Flow (`panOnDrag={[1]}` — middle
* button only) has never done.
*
* **One honest exception to "the chord you see is the chord that fires":** `terminal.copySelection`
* is a registry row whose matcher is still the hardcoded `isCopyShortcut` in
* `terminal/terminal-config.ts` ("the copy chords and Shift+Enter keep their existing owners
* whatever the registry says" — `terminalKeyAction`). Its registry DEFAULTS match that matcher on
* both platforms, so the row is accurate as shipped; a remap of it would not be. Settings already
* offers the same row on the same terms, so the panel does not second-guess it — wiring
* `isCopyShortcut` to the registry is the fix, and it is not this change.
*/
import { Fragment, useEffect } from 'react'
import { createPortal } from 'react-dom'
import { isHoldChord, shortcutKeyParts } from '@shared/shortcut'
import {
COMMAND_DEFINITIONS,
type CommandGroup,
type CommandId
} from '@shared/keybindings'
import { isMacPlatform, keyLabel } from '@shared/platform-utils'
import { isBrowserRuntime } from '../bridge/runtime'
import { effectiveBindings } from '../lib/keybindingOverrides'
import { useSettings } from '../state/settings'
import { resolveFocusFollowsPointer } from '../lib/terminalFocusMode'
import { IconClose } from './icons'
export interface ShortcutsPanelProps {
onClose: () => void
/** Route into Settings → Keyboard Shortcuts. Optional so the panel renders standalone. */
onCustomize?: () => void
}
export interface ShortcutRow {
/** One entry per EFFECTIVE chord, each already split into display badges. A command may hold
* several and the extras are not interchangeable: `canvas.deleteSelection` ships Delete AND
* Backspace, and `terminal.copySelection` ships Ctrl+Shift+C AND Ctrl+Insert off-mac — where
* Chromium reserves Ctrl+Shift+C for the inspector and a page cannot take it back, so in the
* Server Edition Ctrl+Insert is the ONLY one that copies. Printing just the first chord
* advertised the broken one there. */
chords: string[][]
label: string
}
export interface ShortcutSection {
title: string
rows: ShortcutRow[]
note?: string
}
export interface ShortcutSectionsOptions {
isMac: boolean
/** Server Edition (browser tab): a couple of chords are the browser's and can never fire. */
browser: boolean
/** `settings.panHoverDelay`, ms. */
panHoverDelay: number
/** `settings.canvasDragMode` — decides which button box-selects and which pans. */
dragMode: 'select' | 'pan'
/** `settings.doubleClickFocus`. */
doubleClickFocus: boolean
/** `settings.wheelZoom` — a plain wheel zooms too. */
wheelZoom: boolean
/** `settings.terminalFocusFollowsPointer` (issue #757). Off = click to focus: no hover dwell
* ever takes the keyboard, so the dwell row would advertise a gesture that does nothing. */
focusFollowsPointer: boolean
/** Canonical effective binding strings for a command; `[]` when unbound or disabled. */
bindingsFor: (id: CommandId) => readonly string[]
/** `settings.terminalFontZoomKeys` (issue #915). Optional: absent = off, the shipped default. */
terminalFontZoomKeys?: boolean
}
/** The section order IS the registry's group order (first appearance), so a new `CommandGroup`
* gets its own section without an edit here. */
function groupOrder(): CommandGroup[] {
const seen: CommandGroup[] = []
for (const def of COMMAND_DEFINITIONS) if (!seen.includes(def.group)) seen.push(def.group)
return seen
}
/** The one row whose LABEL depends on the chord's SHAPE: a modifier-only dictation chord is
* hold-to-talk, which the title alone does not say. `isHoldChord('')` is TRUE, so the empty
* chord (dictation disabled) is checked first — but such a row is dropped before it gets here. */
function rowLabel(id: CommandId, title: string, chord: string): string {
if (id === 'speech.dictation' && chord !== '' && isHoldChord(chord)) return `${title} (hold)`
return title
}
/** A literal (non-command) row: one chord, spelled out. */
const row = (keys: string[], label: string): ShortcutRow => ({ chords: [keys], label })
/** Gesture / non-command rows appended under a registry group. */
function extraRows(group: CommandGroup, o: ShortcutSectionsOptions): ShortcutRow[] {
if (group === 'General') {
// Desktop only: browsers own Cmd/Ctrl+1-9 for tab switching and a page cannot take it back
// (lib/projectJump.ts rule 1), so listing it in the Server Edition would promise a shortcut
// that never fires.
return o.browser ? [] : [row(['⌘', '1-9'], 'Jump to project')]
}
if (group === 'Canvas') {
return [
row(['Right-click'], 'Actions menu (empty space or node)'),
// React Flow's `selectionOnDrag` / `panOnDrag` follow settings.canvasDragMode, so these
// two rows swap with it rather than describing only the default.
...(o.dragMode === 'pan'
? [
row(['Left-drag'], 'Pan the canvas'),
row(['⇧', 'drag'], 'Box-select (touch to select)')
]
: [
row(['Left-drag'], 'Box-select (touch to select)'),
row(['Middle-drag'], 'Pan the canvas')
]),
row(['Space', 'drag'], 'Pan the canvas (any drag mode)'),
// lib/modifierPan: deliberately ⌘ on mac and Ctrl elsewhere, so spelled per platform.
row([o.isMac ? '⌘' : 'Ctrl', 'middle-drag'], 'Pan the canvas, even while it is locked'),
row(['⇧', 'click'], 'Add a node to the selection'),
...(o.doubleClickFocus
? [row(['Double-click'], 'Center & focus a node')]
: []),
row(['⌘', 'wheel'], 'Zoom in / out'),
...(o.wheelZoom ? [row(['Wheel'], 'Zoom in / out (plain wheel)')] : []),
// Advertised on BOTH surfaces, unlike "Jump to project" above. ⌘1-9 is dropped there
// because the browser RESERVES it (tab switching, un-preventable) for something unrelated;
// ⌘0 is neither — it is not in the reserved set, so the page gets the keydown, and even
// where a browser insists on handling it too it means the same thing we do ("actual size").
// Shift+1 is nobody else's key on any surface. Both live in lib/zoomShortcut.ts, which is
// matched on `e.code` and therefore is not a registry binding.
row(['⌘', '0'], 'Zoom to 100%'),
row(['⇧', '1'], 'Fit view')
]
}
return []
}
/** Terminal facts the registry knows nothing about: tmux owns the mouse, xterm owns two remaps,
* and the hover guard owns the first ~half second (or, in click-to-focus mode, everything until
* the first click). Each verified against the code that
* implements it (see CLAUDE.md "tmux owns the mouse" and terminal/terminal-config.ts). */
function behaviorRows(o: ShortcutSectionsOptions): ShortcutRow[] {
const seconds = Math.round(o.panHoverDelay / 100) / 10
const forceSelect = o.isMac ? '⌥' : 'Shift'
// Click to focus (#757): the terminal takes the keyboard on a click and keeps it until you click
// elsewhere, so ANY drag over an unfocused terminal moves it — there is no "quick" window.
const enter = o.focusFollowsPointer ? [`Hover ${seconds}s`] : ['Click']
const move = o.focusFollowsPointer ? ['Quick drag'] : ['Drag']
return [
row(enter, 'Enter the terminal (type / select)'),
row(move, 'Move the terminal (before it focuses)'),
row(['Wheel'], "Scroll tmux's own history"),
row(['Drag'], 'Select — copies to the system clipboard'),
row([forceSelect, 'drag'], 'Select in the emulator (apps that grab the mouse)'),
row(['⇧', 'Enter'], 'Insert a newline instead of submitting'),
row(['⌘', 'click'], 'Open a link, file or folder from the output'),
row(['✦'], 'Name the terminal with AI'),
// Opt-in (issue #915), so only listed when on. Spelled per platform rather than with the
// panel's usual ⌘ glyph: this chord is deliberately ⌘ on mac and Ctrl elsewhere, never either
// (terminal-font-zoom.ts), and advertising ⌘ off-mac would name a key that does nothing.
...(o.terminalFontZoomKeys
? [
row([o.isMac ? '⌘' : 'Ctrl', '+ / −'], 'Terminal font size bigger / smaller'),
row([o.isMac ? '⌘' : 'Ctrl', '0'], 'Terminal font size back to the global size')
]
: [])
]
}
/** Registry rows + the literal rows, as the panel renders them. Pure: every input is a value,
* so the parity test can drive it without a settings store or a DOM. */
export function buildShortcutSections(o: ShortcutSectionsOptions): ShortcutSection[] {
const sections: ShortcutSection[] = []
for (const group of groupOrder()) {
const rows: ShortcutRow[] = []
for (const def of COMMAND_DEFINITIONS) {
if (def.group !== group) continue
const chords = o.bindingsFor(def.id)
const chord = chords[0]
if (!chord) continue // unbound, or the user disabled it — no key to advertise
rows.push({
chords: chords.map((c) => shortcutKeyParts(c, o.isMac)),
label: rowLabel(def.id, def.title, chord)
})
}
rows.push(...extraRows(group, o))
if (rows.length) sections.push({ title: group, rows })
}
sections.push({ title: 'Terminal behavior', rows: behaviorRows(o) })
// These are platform/program keys, not remappable nodeterm commands. A configured agent
// cannot prove the foreground program reads images from this viewer's clipboard (#712).
if (o.isMac) {
sections.push({
title: 'Pasting screenshots on macOS',
rows: [
row(['⌘', 'V'], 'Save the image and paste its file path'),
row(['Ctrl', 'V'], 'Send a control key to the foreground program')
],
note: o.browser
? 'In Server Edition, the image is uploaded to the terminal host. Ctrl+V does not transfer your browser clipboard to that host. Image paste depends on browser clipboard access.'
: 'A local agent that supports clipboard images (such as Claude Code) may attach an image with Ctrl+V. Use it only at that agent’s input prompt; shells and editors give this key other meanings. For SSH sessions, use Cmd+V to upload the image and paste its remote path. nodeterm does not detect image support or retry with the other route.'
})
}
return sections
}
/** Keyboard shortcuts reference; shown on first launch and via ⌘/ or the ? button. */
export function ShortcutsPanel({ onClose, onCustomize }: ShortcutsPanelProps) {
// Subscribing to the overrides object is what makes a remap land in an ALREADY-OPEN panel
// (Settings in another window, or an outside edit to settings.json the store watcher picks up):
// `effectiveBindings` is a plain read, not a subscription, so without this the rows would keep
// the chords they were built with. The value is unused on purpose.
useSettings((s) => s.settings.keybindings)
// Narrow primitive selectors: an unrelated settings write must not re-render the panel.
const panHoverDelay = useSettings((s) => s.settings.panHoverDelay)
const dragMode = useSettings((s) => s.settings.canvasDragMode)
const doubleClickFocus = useSettings((s) => s.settings.doubleClickFocus)
const wheelZoom = useSettings((s) => s.settings.wheelZoom)
const terminalFontZoomKeys = useSettings((s) => s.settings.terminalFontZoomKeys)
const focusFollowsPointer = resolveFocusFollowsPointer(
useSettings((s) => s.settings.terminalFocusFollowsPointer)
)
const isMac = isMacPlatform()
const sections = buildShortcutSections({
isMac,
browser: isBrowserRuntime(),
panHoverDelay,
dragMode: dragMode === 'pan' ? 'pan' : 'select',
doubleClickFocus,
wheelZoom,
terminalFontZoomKeys,
focusFollowsPointer,
bindingsFor: effectiveBindings
})
useEffect(() => {
const onKey = (e: KeyboardEvent) => {
if (e.key === 'Escape') onClose()
}
window.addEventListener('keydown', onKey)
return () => window.removeEventListener('keydown', onKey)
}, [onClose])
return createPortal(
<div className="sc-overlay" onClick={onClose}>
<div className="shortcuts" onClick={(e) => e.stopPropagation()}>
<div className="shortcuts__head">
<h2>Keyboard shortcuts</h2>
<button className="drawer__close" aria-label="Close" onClick={onClose}>
<IconClose />
</button>
</div>
<div className="shortcuts__body">
{sections.map((s) => (
<section key={s.title}>
<h3>{s.title}</h3>
{s.rows.map((r, i) => (
<div key={`${r.label}-${i}`} className="shortcut-row">
<span className="shortcut-label">{r.label}</span>
<span className="shortcut-keys">
{r.chords.map((chord, ci) => (
<Fragment key={ci}>
{ci > 0 && <span className="shortcut-or">or</span>}
{chord.map((k, i) => (
<kbd key={i} className="kbd">
{keyLabel(k, isMac)}
</kbd>
))}
</Fragment>
))}
</span>
</div>
))}
{s.note && <p className="shortcuts__note">{s.note}</p>}
</section>
))}
</div>
{onCustomize && (
<div className="shortcuts__foot">
<span>Unassigned commands and remapping live in Settings.</span>
<button className="shortcuts__customize" onClick={onCustomize}>
Customize…
</button>
</div>
)}
</div>
</div>,
document.body
)
}