/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 plugin | | `~` | prev-plugin | Previous plugin | | `1-5` | focus-plugin-N | Focus plugin by number | | `?` | toggle-palette | Command palette | | `!` | toggle-diagnostics | Diagnostics overlay | | `@` | switch-project | Project switcher | | `W` | switch-worktree | Worktree switcher | | `#` | switch-theme | Theme switcher | | `i` | open-issue | Open issue | | `r` | refresh | Refresh | | `q` | quit | Quit (root contexts only) | | `ctrl+c` | quit | Force quit |

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.

| Key | Action | |-----|--------| | `h` / `l` / `left` / `right` | Move between lanes | | `j` / `k` / `up` / `down` | Move within a lane | | `enter` | Open the selected workspace (switches project) | | `r` | Refresh the board | | `esc` / `q` / `K` | Close the Overview |

Global shortcuts stay live while it is open: `` ` ``/`~`, `1-9`, `@`, `#`, `W`, `?`, `!`, `^`, `i`, `ctrl+c`. Plugin-switching keys (`` ` ``, `~`, `1-9`) close the Overview first. `q` closes the Overview instead of quitting the app.

Sidebar Controls (All Two-Pane Plugins)

| Key | Action | |-----|--------| | `Tab` / `Shift+Tab` | Switch focus between panes | | `\` | Toggle sidebar visibility | | `h` / `left` | Focus left pane | | `l` / `right` | Focus right pane | | `+` | Grow sidebar width | | `-` | Shrink sidebar width |

Git Status Plugin

Contexts

| Context | View | |---------|------| | `git-status` | File list (root) | | `git-status-commits` | Recent commits sidebar (root) | | `git-status-diff` | Inline diff pane (root) | | `git-commit-preview` | Commit detail in right pane | | `git-diff` | Full-screen diff | | `git-commit` | Commit editor | | `git-push-menu` | Push strategy selection | | `git-pull-menu` | Pull strategy selection | | `git-pull-conflict` | Conflict resolution | | `git-history` | Commit history | | `git-commit-detail` | Single commit view |

File List Shortcuts

| Key | Command | Description | |-----|---------|-------------| | `s` | stage-file | Stage selected file | | `u` | unstage-file | Unstage selected file | | `S` | stage-all | Stage all modified | | `U` | unstage-all | Unstage all | | `c` | commit | Open commit editor | | `A` | amend | Amend last commit | | `d` / `enter` | show-diff | View file changes | | `D` | discard-changes | Discard unstaged changes | | `h` | show-history | Open commit history | | `P` | push | Open push menu | | `L` | pull | Open pull menu | | `f` | fetch | Fetch from remote | | `b` | branch | Branch operations | | `z` | stash | Stash changes | | `Z` | stash-pop | Pop stash | | `ctrl+z` | stash-apply | Stash apply | | `o` | open-in-github | Open in GitHub | | `O` | open-in-file-browser | Open in file browser | | `y` | yank-file | Copy file info | | `Y` | yank-path | Copy file path |

Commit List Shortcuts

| Key | Command | Description | |-----|---------|-------------| | `enter` / `d` | view-commit | Open commit details | | `h` | show-history | Open history view | | `y` | yank-commit | Copy commit as markdown | | `Y` | yank-id | Copy commit hash | | `/` | search-history | Search commit messages | | `f` | filter-author | Filter by author | | `p` | filter-path | Filter by path | | `F` | clear-filter | Clear filters | | `n` | next-match | Next search match | | `N` | prev-match | Previou