Keyboard Shortcuts

Keyboard Shortcuts

Complete shortcut listings and context reference for all sidecar plugins. For implementation patterns, see docs/guides/deprecated/ui-feature-guide.md. For a detailed assessment of inconsistencies, vim alignment, mnemonic quality, and improvement proposals, see references/assessment.md in this skill directory.

Architecture

• Centralized binding registry: internal/keymap/bindings.go is the single source of truth for key bindings.
• Context-based dispatch: Each plugin defines contexts; bindings are scoped to contexts.
• Command palette (?): Auto-discovers bindings for discoverability.
• User overrides: Supported via ~/.config/sidecar/config.json.
• Key sequences: Compound commands like g g are supported with 500ms timeout.

Adding a New Shortcut

1. Add the binding in internal/keymap/bindings.go under the appropriate context.
2. Add command handling in the plugin's Update() method (usually in a handlers.go file).
3. Add the command to the plugin's Commands() method for footer hint and command palette.
4. Keep command names short (1 word preferred) to prevent footer wrapping.

TD Monitor Shortcuts

TD shortcuts are dynamically exported from TD itself via ExportBindings() and ExportCommands() in pkg/monitor/keymap/. TD is the single source of truth. To add TD shortcuts:

1. Add binding to TD's pkg/monitor/keymap/bindings.go
2. Add command constant to TD's pkg/monitor/keymap/registry.go
3. Add metadata to TD's pkg/monitor/keymap/export.go
4. Handle in TD's pkg/monitor/model.go

Global Shortcuts

The header row is one ring

Sidecar's header is a single row of entries: the global ones in the left cluster (Sessions, Activity, and Tasks when its feature is on) followed by the project's plugin tabs on the right.

[ / ] (and their ~ / ` aliases) wrap through **all** of it, in that order, and the ring is identical from either scope — the project tabs are painted only in project scope, but they stay in the ring from the global space so the cycle is never a trap and ] then [ is always the identity. Tasks is absent from the ring whenever its feature is off.

The number row addresses the same row, but by two different rules:

• 1-7 are positional project tabs. They stop at 7. An eighth plugin tab is reached with [ / ] or from the command palette.
• 8 / 9 / 0 are named global entries — Sessions, Activity, Tasks — and mean the same thing in every scope. A key whose entry is disabled (0 with the Tasks host off) does nothing at all, silently; it never falls through to a plugin tab.

All ten digits and the four cycling keys are in keymap.GlobalKeys, so no plugin may claim them, and all of them yield to a focused text input.

Configuration (config / config-edit / config-confirm contexts)

Opened with , or by clicking the header gear, always on Sidecar Setup. Like the Overview, Configuration covers the plugin pane and owns keyboard focus: unhandled keys are swallowed rather than leaking to the hidden plugin. ? still opens the command palette.

Agent Overview (overview context)

Opened with K or by clicking the Sidecar logo. The Overview covers the plugin pane and owns keyboard focus: a plugin left in interactive/text-input mode underneath it (embedded shell, inline editor) does not receive keys while it is open, and unhandled keys are swallowed rather than leaking to the hidden plugin.

Global shortcuts stay live while it is open: `/~, [/], 1-9, @, #, W, ?, !, ^, i, ctrl+c, q. Plugin-switching keys (`, ~, 1-9) close the Overview first. esc on the Agents board or Workspaces list leaves the global space. q opens Sidecar's quit modal.

Global Workspaces

Contexts: global-workspaces (list, root), global-workspaces-filter, global-workspaces-rename, global-workspaces-create, global-workspaces-delete, global-workspaces-terminal (typing), global-workspaces-doc, global-workspaces-doc-search, global-workspaces-doc-find, global-workspaces-issue, global-workspaces-diff.

There is no watched-preview focus: hiding the sidebar is layout only. l / → do not move focus to the preview. Clicking a file or td id focuses a content leaf with its own context; footer, help, and the palette follow WorkspaceFocusContext().

ctrl+] attach stays project-only and is off unless tmux_full_attach is enabled. While typing, i and q go to the pane.

Focused document (global-workspaces-doc)

Same keys as the project document pane: q/esc close, x close tab, {/} cycle tabs, m toggle render, Y yank path — and the same three searches, all rooted at the pane's own directory: / in-file search, ctrl+p file finder, f project search. The finder and project search are internal/panesearch; the in-file bar is internal/docview. Contexts while one is up: global-workspaces-doc-search and global-workspaces-doc-find.

Focused issue (global-workspaces-issue)

An unmodified click on a td-… link opens it beside the terminal. A second click appends a tab; an already-open ID is focused. Click a drawn tab to select it. The header is only the tab strip: ID plus headline, truncated at the end so the ID stays visible. Footer hints are Tab× Tab← Tab→. There is no close chip.

enter on a parent or subtask uses the same open-or-focus path (no duplicate, no silent replace). Tabs stay in memory for the selected row and are not written to disk.

Project issue pane (workspace-issue)

Same open/append/click/cycle/close journey and the same { / } / x / yank / enter keys. tab / shift+tab cycle panes; \ toggles the sidebar. q / esc hide the pane and retain tabs for that surface; last x forgets. Switching shells or relaunching restores tabs, the active tab, and each tab's scroll.

Sidebar Controls (All Two-Pane Plugins)

Git Status Plugin

Contexts

File List Shortcuts

Inline Diff Pane (git-status-diff)

The right-hand pane of the Git tab, focused with enter / l from the file list.

| is vim's goto-column key. It reads as the odd choice next to vim's 0, and 0 is what this pane used to bind — but the whole number row belongs to the header (see "The header row is one ring"), so 0 never reaches the plugin. It was a live handler that had quietly stopped being reachable; | is the replacement, and unlike 0 it is registered, so it appears in the footer and in ?.

Full-Screen Diff (git-diff)

This view has no tabs, so { / } are deliberately unbound here rather than made to mean "next file" — that would be the one place in Sidecar where a brace did something other than cycle tabs, and a silent wrong action is worse than a no-op. File stepping is , / ., the same as in the Workspaces Diff pane.

Commit List Shortcuts

Pull Menu

File Browser Plugin

Contexts

Tree Shortcuts

A file opened in an app content pane beside Files uses the shared workspace-doc document context. It keeps the same file-facing shortcuts as the primary Files preview wherever the shared viewer owns the capability: / InFile, ctrl+p Find, f Search, e inline Edit, E external Editor, r Reload, m Render, w Wrap, I Info, ctrl+r Reveal, y Contents, Y Path, configured selection copy/select-all, { / } tabs, and + / - resize. Its finder and project search are the same internal/panesearch surfaces used by project and global Workspace document panes, rooted at that content deck's project and loading results back into the focused pane. Files-only tree operations such as rename and its full-screen blame mode remain owned by the primary Files surface; they are not document-viewer shortcuts and are not forwarded to a potentially different file behind the focused pane.

Conversations Plugin

Contexts

Workspaces Plugin

Contexts

List Shortcuts

Preview Shortcuts

The Pane Switcher Is Reachable From Every Pane

n opens the pane switcher whenever a content pane has focus — Document, Issue, Note, Diff or Resource — on both the project workspace (workspace-doc|issue|note|diff|resource) and the global Workspaces browser (global-workspaces-doc|issue|note|diff|resource). Every content pane absorbs the keys it does not own, so without this the switcher was reachable only from the sidebar or the terminal: putting a second pane beside the one you were reading meant leaving it first.

n is the same key the sidebar and the terminal preview already answer with "make me a new thing", so the answer does not change with focus. Two consequences follow, and both are deliberate:

• The Diff pane's n / N next-change pair moved to > / < — the shifted forms of its , / . file steps, so the pair reads as one hierarchy: step a file, shift to step a change inside it. One key means one thing in every pane; a key that meant next-change here and "new pane" everywhere else is exactly the drift this codebase refuses.
• A live input surface inside a pane still wins. A committed in-file search owns n for its next-match while it is up, as does the doc editor and the finder overlay; the switcher is asked only after they decline.

The terminal preview keeps o rather than n, because n there belongs to the list's create. internal/keymap's parity tests hold both surfaces to the same key in the same contexts.

The plugin half: ctrl+n

The same entry exists in the ordinary plugins, under ctrl+n rather than n. Every plugin that has a create already spends n on it — new-note, next-match — so displacing those would be the drift the Workspaces half deliberately avoided.

It is bound in one place for all five plugins: internal/app/pane_switcher.go, not once per plugin. The deck the switcher opens into is the app's (internal/app/content_deck.go) and so is the key routing, so a plugin opts in simply by being deck-eligible — implementing plugin.ContentLinkProvider and plugin.PaneFocusProvider, with features.PluginContentPanes on. Today that is file-browser, git-status, notes, tasks and td-monitor; workspace is excluded because it owns its own pane tree.

Three rules decide where the key appears, and none of them is a per-plugin list:

• The keymap is the whole opt-in. The host reads the entry key out of the keymap for whatever context is active (paneSwitcherKeyFor) rather than comparing against a constant. A context that never names open-pane never reaches the switcher, and a user who rebinds open-pane moves the key and its footer hint together.
• Browse and preview contexts only. ctrl+n is cursor-down in the global context and in every filter, finder, search and editor context. Claiming it where it already walks a list would take the cursor out from under someone who is typing, so those contexts keep it. See the assignment table below.
• A focused passive leaf answers n, not ctrl+n. A leaf inside a plugin's deck reports the same workspace-doc|issue|note|diff|resource context the two Workspaces surfaces report for the same pane, so it answers the same key there. One model, three projections, one key each.

The switcher offers pane kinds only outside Workspaces — File, Git diff, td issue, Note, one row per configured resource provider — and is titled "Open Pane" rather than "Create Workspace". Shell and Worktree create workspace rows, which a Notes plugin has nowhere to put; Terminal split is absent because a plugin deck is a passive contentpanes deck with no live-leaf host. That is workspacecreate.OpenOpts.PaneKindsOnly plus AllowTerminalSplit: false — the same data-driven catalog, one more flag, no second modal.

See docs/plans/active/pane-switcher-everywhere.md.

Where ctrl+n goes, in full

Every context that binds ctrl+n in keymap.DefaultBindings(), and to what. internal/keymap/pane_switcher_parity_test.go holds this table to the tree.

Contexts deliberately without a row, and the reason each is different:

• notes-preview — the note preview answers ctrl+n/ctrl+p as its own cursor motion in plugin code (notes.handleEditorPreviewKey), with nothing in bindings.go to show for it. The rule stands aside; Notes stays reachable from notes-list.
• td-modal and its sub-focus states (td-epic-tasks, td-parent-epic, td-blocked-by-focused, td-blocks-focused) — tdmonitor.BlocksGlobalKeys hands every key in that context to the embedded td model at precedence level 2, two rungs above the switcher's, so a binding there would never fire. This is the one genuinely wanted pane the entry does not reach.
• td-search, td-form, td-board-editor, td-confirm, td-close-confirm, and every non-root tasks-* context — text input or an overlay the plugin forwards wholesale.
• git-history — has bindings in bindings.go but gitstatus.FocusContext() never reports it. A binding on a context nobody stands in is a key that does nothing.
• Anything reaching a live PTY. ctrl+n is a real control character: tty.MapKeyToTmux encodes it as C-n and sends it to the pane. The tty layer's own chords are ctrl+\ (exit), ctrl+] (attach), alt+c (copy), alt+v (paste), ctrl+a (select all) and the platform copy chord; its scrollback set is the arrows plus the j/k/g/G/ctrl+d/ctrl+u pager aliases. The two host OnKey hooks claim only terminal search and ctrl+t. Above all of that, workspace-interactive, file-browser-inline-edit, notes-inline-edit and workspace-doc-edit forward every key two rungs before the switcher's is reached.

g / G jump to the top / bottom of the preview's scrollback. 0 is deliberately not bound here: it is the header's global Tasks shortcut, and a context-local binding would make the same key mean two different things one tab apart. (It previously carried a reset-scroll command that had no handler anywhere in the tree.)

M Opens the Reposition Modal From Every Pane

M (move-pane, feature pane_move, default on) opens the shared pane reposition modal — the same modal the pane header's ⊞ button opens, and the same one for all three pane hosts. It is an entry point, not a second interaction: M never mutates the live tree by itself. Inside the modal, h/j/k/l and the arrows edit a draft, z toggles zoom, enter commits the whole sequence atomically, and esc discards it.

Which pane it targets depends on which window owns the keyboard:

• From a focused pane — a preview, a document, an issue, a note, a diff, a resource — M targets that leaf.
• From either Workspaces list (workspace-list, and global-workspaces, which the Sessions surface also reports for a focused Primary terminal) M targets the selected row's Primary terminal. Host focus decides which of the two the shared global-workspaces context means.
• From a plugin content deck the key is answered on the app's own structural rung, so it targets the focused passive leaf and never the primary plugin leaf underneath.

Bound contexts (all feature-gated on pane_move): workspace-list, workspace-preview, workspace-doc, workspace-issue, workspace-note, workspace-diff, workspace-resource, global-workspaces, global-workspaces-doc, global-workspaces-issue, global-workspaces-note, global-workspaces-diff, global-workspaces-resource. The app content decks report the same workspace-* context names for their own leaves and inherit these bindings.

Not bound in text-input, interactive-terminal, modal, or unrelated plugin browse contexts — workspace-filter, workspace-interactive, workspace-doc-edit|search|find, global-workspaces-filter, global-workspaces-terminal, file-browser-tree, git-status, notes-list, and the rest. Those contexts keep every printable key for themselves, and internal/keymap/pane_move_parity_test.go holds them to it.

Why M and not m. m is free in ten of the twelve pane contexts, and taken in exactly the two that would break parity: global-workspaces-doc spends it on render, and global-workspaces (what a focused Primary terminal reports on the Sessions surface) spends it on merge-workflow. One key must mean one thing in every pane, so a key that works in ten and not the other two is not a candidate. M is bound nowhere else except git-status (stash-pop), a plugin browse context that is never a pane leaf.

A pane with nowhere to go has no entry. A tree with a single leaf offers neither the key's modal nor the header's ⊞: PlanMove refuses every destination on it, so both would open onto a layout that cannot change. The button appears when a second pane does.

The agent's half of the same capability is sidecar layout move over the same planner, with --to left|right|up|down compiling through the identical direction rule. See .claude/skills/ui-features/SKILL.md and docs/reference/cli.md.

Interactive Mode

Document Pane

An unmodified click on a resolvable file path in workspace or shell terminal output opens it beside that terminal. A second click appends a tab; a path that is already open is focused (and path:line jumps). Click a drawn tab to select it. The header is only the tab strip: each label is the relative path, left-truncated so the filename end always wins. Document panes are enabled by default; --disable-feature=workspace_doc_panes opts out for a launch and also disables Diff (no pane tree). shift-drag and alt-drag remain terminal selection gestures.

The global Workspaces view uses the same tab strip and the same click / { / } / x keys. Those tabs stay in memory for the selected row.

q / esc hide the pane and remember the tab set for this shell or workspace. x on the last tab forgets the set. Switching surfaces or relaunching onto the same surface restores open files, the active tab, render mode, wrap, scroll, and split ratio. , / . cycle Diff target tabs only while a Diff leaf is focused; they do not cycle document tabs.

While a pane search is open (workspace-doc-search) it owns every key in the pane: esc closes it, enter loads the hit in the active tab, and shift+enter opens it in a new tab.

Inline edit (e) opens the same tmux-PTY editor the Files plugin uses, sized to the pane body, on both pane surfaces (workspace-doc-edit and the global browser's document pane). While a session is live every key is the editor's — ctrl+\ or esc esc exit it — and clicking outside the pane raises the save / discard / cancel confirmation instead of leaving the buffer behind.

In-file search (/) is a third surface, drawn by internal/docview as one row inside the pane, and it owns every key while it is up (workspace-doc-find, global-workspaces-doc-find): enter commits, n / N step matches, esc closes. It dismisses when the pane loses focus. While it is up it also keeps n away from the pane switcher, which is asked only after the pane's own input surfaces decline.

Diff Pane

d / show-diff on the Workspaces list or preview opens a working-tree Diff leaf beside the terminal. The leaf is not a root context: q / esc hide it. { / } cycle Diff target tabs while the leaf is focused; , / . step next/prev file inside the view, and > / < step next/prev change inside a file (this pair was n / N until the pane switcher took n in every content pane).

One rule everywhere: { / } is always "cycle the tabs of the thing I am looking at." Document, issue, File Browser and Diff leaves all obey it. The Diff pane is the only surface with a second navigation axis — the files inside the active target — and that axis gets its own pair, , / ..

The earlier arrangement was the reverse ({ / } = file, , / . = tab), on the reasoning that in-view file jumping is the more frequent act in a diff and so deserved the better-known keys. That reasoning was sound in isolation and wrong in aggregate: it made the diff the one place in Sidecar where } did not mean "next tab", so the cost was paid on every context switch into and out of the diff, by everyone, forever — while the benefit accrued only inside the diff. Consistency of a key's meaning across surfaces beats optimality of its assignment on one surface. If you are tempted to re-optimise a key for a single pane again, that is the trade to weigh.

Moving around inside the viewer. These are the shared viewer's own keys (internal/workspacediff/keys.go); they are registered in bindings.go for both workspace-diff and global-workspaces-diff so the footer, help and palette show them, and the viewer answers them before keymap dispatch.

Issue Pane

An unmodified click on a td-… link in workspace or shell terminal output opens it beside that terminal. A second click appends a tab; an ID that is already open is focused. Click a drawn tab to select it. The header is only the tab strip: each label is the issue ID plus headline, truncated at the end so the ID stays visible. There is no close chip. Footer hints are Tab× Tab← Tab→.

The global Workspaces view uses the same tab strip and the same click / { / } / x keys. Those tabs stay in memory for the selected row and are not written to disk. q / esc and last-x forget that row's set.

In project Workspaces, q / esc hide the pane and remember the tab set for this shell or workspace. x on the last tab forgets the set. Switching surfaces or relaunching onto the same surface restores open issues, the active tab, and each tab's scroll. Parent and subtask enter uses the same open-or-focus path.

File tabs keep left-truncated paths so the filename survives. Issue tabs keep the ID visible and truncate the headline.

…(truncated)