/keyboard-shortcuts

name: keyboard-shortcuts
description: >
  Reference for keyboard shortcut implementation, keybinding registration,
  shortcut parity with vim and other TUI tools, and the complete shortcut
  assignment table across all sidecar plugins. Use when adding or modifying
  keyboard shortcuts, checking shortcut assignments, resolving key conflicts,
  or assessing alignment with vim conventions.

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

| Key | Command | Description | |-----|---------|-------------| | `j` / `down` | cursor-down | Move cursor down | | `k` / `up` | cursor-up | Move cursor up | | `G` | cursor-bottom | Jump to bottom | | `g g` | cursor-top | Jump to top | | `ctrl+d` | page-down | Page down | | `ctrl+u` | page-up | Page up | | `enter` | select | Select item | | `esc` | back | Go back / close | | `` ` `` | next-plugin | Next header entry | | `~` | prev-plugin | Previous header entry | | `]` | next-plugin | Next header entry | | `[` | prev-plugin | Previous header entry | | `1`-`7` | focus-plugin-N | Focus the Nth project tab (positional; stops at 7) | | `8` | focus-sessions | Sessions (global) | | `9` | focus-activity | Activity (global) | | `0` | focus-tasks | Tasks (global; no-op when the Tasks host is disabled) | | `?` | toggle-palette | Command palette | | `!` | toggle-diagnostics | Diagnostics overlay | | `@` | switch-project | Project switcher | | `W` | switch-worktree | Worktree switcher | | `#` | switch-theme | Theme switcher | | `,` | open-configuration | Open Configuration (contexts that bind `,` win) | | `i` | open-issue | Open issue | | `r` | refresh | Refresh | | `q` | quit | Quit (root contexts only) | | `ctrl+c` | quit | Force quit |

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.

| Key | Command | Context | Action | |-----|---------|---------|--------| | `j` / `k` / `up` / `down` | cursor-down / cursor-up | config | Move through sidebar destinations | | `enter` | select | config | Open the selected destination | | `/` | search | config | Focus Search (enters `config-edit`) | | `tab` | focus-search | config | Move focus between sidebar and Search | | `esc` | close-configuration | config | Return from a child route, else close and restore the prior surface | | `down` | first-result | config-edit | Move from Search to the first visible result | | `up` | focus-search | config-edit | Return to Search from the first result | | `esc` | clear-search | config-edit | Clear the query and restore the full sidebar | | `enter` / `y` | confirm | config-confirm | Confirm a consequential change | | `esc` / `n` | cancel | config-confirm | Cancel it |

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 p