| 1 | # Keybindings |
| 2 | |
| 3 | This is the source-of-truth catalog of every keyboard shortcut the TUI recognizes. Bindings are grouped by **context** — the focus or modal state they fire in. A binding listed under "Composer" only takes effect when the composer is focused; one under "Transcript" only when the transcript has focus; and so on. |
| 4 | |
| 5 | Bindings are not (yet) user-configurable — tracked for a future release (#436, #437). This document is the contract that future config-file overrides will name into. |
| 6 | |
| 7 | ## Global (any context) |
| 8 | |
| 9 | | Chord | Action | |
| 10 | |----------------------|---------------------------------------------------------------| |
| 11 | | `F1` or `Ctrl-?` | Toggle the help overlay | |
| 12 | | `Ctrl-K` | Open the command palette (slash-command finder) | |
| 13 | | `Ctrl-C` | Cancel current turn / dismiss modal / arm-then-confirm quit | |
| 14 | | `Ctrl-D` | Quit (only when the composer is empty) | |
| 15 | | `Tab` | Cycle TUI mode: Plan → Agent → YOLO → Plan | |
| 16 | | `Shift-Tab` | Cycle reasoning effort: off → high → max → off | |
| 17 | | `Ctrl-R` | Open the resume-session picker | |
| 18 | | `Ctrl-L` | Refresh / clear the screen | |
| 19 | | `Ctrl-Shift-E` / `Cmd-Shift-E` | Toggle the file-tree sidebar | |
| 20 | | `Esc` | Close topmost modal · cancel slash menu · dismiss toast | |
| 21 | |
| 22 | ## Composer |
| 23 | |
| 24 | Editing the message you're about to send. |
| 25 | |
| 26 | | Chord | Action | |
| 27 | |-----------------------------|---------------------------------------------------------| |
| 28 | | `Enter` | Send the message (or run the slash command) | |
| 29 | | `Alt-Enter` / `Ctrl-J` | Insert a newline without sending | |
| 30 | | `Ctrl-U` | Delete to start of line | |
| 31 | | `Ctrl-W` | Delete previous word | |
| 32 | | `Ctrl-A` / `Home` | Move to start of line | |
| 33 | | `Ctrl-E` / `End` | Move to end of line | |
| 34 | | `Ctrl-←` / `Alt-←` | Move backward one word | |
| 35 | | `Ctrl-→` / `Alt-→` | Move forward one word | |
| 36 | | `Ctrl-V` / `Cmd-V` | Paste from clipboard (also bracketed-paste auto-handled)| |
| 37 | | `Ctrl-Y` | Yank (paste) from kill buffer | |
| 38 | | `↑` / `↓` | Cycle composer history (also selects popup/attachment items) | |
| 39 | | `Ctrl-P` / `Ctrl-N` | Cycle composer history (alternative) | |
| 40 | | `Ctrl-S` | Stash current draft (`/stash list`, `/stash pop` to recover) | |
| 41 | | `Alt-R` | Search prompt history (Alt-R to exit) | |
| 42 | | `Tab` | Slash-command / `@`-mention completion (popup-aware) | |
| 43 | | `Ctrl-O` | Open external editor for the composer draft | |
| 44 | |
| 45 | ### `@` mentions |
| 46 | |
| 47 | Type `@<partial>` to open the file mention popup. `↑`/`↓` cycle the entries, `Tab` or `Enter` accepts. `Esc` hides the popup. As of v0.8.10 (#441), completions are re-ranked by mention frecency — files you mention often + recently float to the top. |
| 48 | |
| 49 | ### `#` quick-add (memory) |
| 50 | |
| 51 | When `[memory] enabled = true`, typing `# foo` and pressing `Enter` appends `foo` as a timestamped bullet to your memory file *without* sending a turn. See `docs/MEMORY.md`. |
| 52 | |
| 53 | ## Transcript (when transcript has focus) |
| 54 | |
| 55 | | Chord | Action | |
| 56 | |----------------------|-----------------------------------------------------| |
| 57 | | `↑` / `↓` / `j` / `k`| Scroll one line (v0.8.13+: bare arrows also scroll when composer empty) | |
| 58 | | `PgUp` / `PgDn` | Scroll one page | |
| 59 | | `Home` / `g` | Jump to top | |
| 60 | | `End` / `G` | Jump to bottom | |
| 61 | | `Esc` | Return focus to composer | |
| 62 | | `y` | Yank selected region to clipboard | |
| 63 | | `v` | Begin / extend visual selection | |
| 64 | | `o` | Open URL under cursor (OSC 8 capable terminals) | |
| 65 | |
| 66 | ## Sidebar (when sidebar has focus) |
| 67 | |
| 68 | | Chord | Action | |
| 69 | |----------------------|-----------------------------------------------------| |
| 70 | | `↑` / `↓` / `j` / `k`| Move selection | |
| 71 | | `Enter` | Activate the selected item (open / focus / cancel) | |
| 72 | | `Tab` | Cycle to next sidebar panel (Files → Tasks → Agents → Todos) | |
| 73 | | `Esc` | Return focus to composer | |
| 74 | |
| 75 | ## Slash-command palette (after `Ctrl-K` or typing `/`) |
| 76 | |
| 77 | | Chord | Action | |
| 78 | |----------------------|-----------------------------------------------------| |
| 79 | | `↑` / `↓` | Move selection | |
| 80 | | `Enter` / `Tab` | Run / complete the highlighted command | |
| 81 | | `Esc` | Dismiss palette | |
| 82 | |
| 83 | ## Approval modal (when a tool requests approval) |
| 84 | |
| 85 | | Chord | Action | |
| 86 | |----------------------|-----------------------------------------------------| |
| 87 | | `y` / `Y` | Approve once | |
| 88 | | `a` / `A` | Approve all (auto-approve subsequent calls) | |
| 89 | | `n` / `N` / `Esc` | Deny | |
| 90 | | `e` | Edit the approved input before running | |
| 91 | |
| 92 | ## Onboarding (first-run flow) |
| 93 | |
| 94 | | Chord | Action | |
| 95 | |----------------------|-----------------------------------------------------| |
| 96 | | `Enter` | Advance to next step (Welcome → Language → API → …) | |
| 97 | | `Esc` | Step back one screen | |
| 98 | | `1`–`5` | Pick a language (Language step) | |
| 99 | | `y` / `Y` | Trust the workspace (Trust step) | |
| 100 | | `n` / `N` | Skip the trust prompt | |
| 101 | |
| 102 | ## v0.8.13 audit notes |
| 103 | |
| 104 | - **Ctrl-S is stash, not history search.** Fixed in this revision — `Alt-R` is history search. |
| 105 | - **Phantom `Alt+Up` removed.** The "Edit last queued message" binding was listed in README but never existed in the key dispatch code. |
| 106 | - **Bare Up/Down arrows scroll transcript when composer empty (v0.8.13).** Previously the `should_scroll_with_arrows` gate was hardcoded to false, meaning bare arrows always navigated composer history even when the composer was empty. Users in virtual terminals (Ghostty, Codex, Kitty-protocol) were especially affected because they couldn't use Cmd+Up / Alt+Up shortcuts. |
| 107 | - **Configurable keymap (#436) and `tui.toml` (#437) remain deferred.** The `TuiPrefs` struct and loader exist in `settings.rs` but are not wired at startup. The named-binding registry that would let `~/.deepseek/tui.toml` override individual entries is still pending. |
| 108 | - **No other broken bindings found.** Every other chord listed above resolves to a live handler in `crates/tui/src/tui/ui.rs` (key-event dispatch) or `crates/tui/src/tui/app.rs` (mode + state transitions). |
| 109 |