# Keyboard Shortcuts Guide

This document lists all available keyboard shortcuts and features in SNOW AI CLI.

## Table of Contents

- [Basic Editing](#basic-editing)
- [Cursor Movement](#cursor-movement)
- [Text Deletion](#text-deletion)
- [Mode Switching](#mode-switching)
- [Navigation and Selection](#navigation-and-selection)
- [Clipboard Operations](#clipboard-operations)
- [Command Execution Control](#command-execution-control)
- [History and Rollback](#history-and-rollback)
- [Panels and Pickers](#panels-and-pickers)

## Basic Editing

| Shortcut               | Function         | Description                                           |
| ---------------------- | ---------------- | ----------------------------------------------------- |
| `Enter`                | Submit Message   | Send the current input message to AI                  |
| `Ctrl+Enter`           | Insert Newline   | Insert a new line in the input box without submitting |
| `Ctrl+G`               | External Editor  | Open Notepad to edit current input (Windows only)     |
| `Backspace` / `Delete` | Delete Character | Delete the character before the cursor                |

## Cursor Movement

### Readline Compatible Shortcuts

| Shortcut             | Function          | Description                                                       |
| -------------------- | ----------------- | ----------------------------------------------------------------- |
| `Ctrl+A`             | Beginning of Line | Move cursor to the start of current line                          |
| `Ctrl+E`             | End of Line       | Move cursor to the end of current line                            |
| `Alt+F` / `Option+F` | Forward One Word  | Jump to the beginning of next word (supports CJK punctuation)     |
| `Alt+B` / `Option+B` | Backward One Word | Jump to the beginning of previous word (supports CJK punctuation) |
| `↑`                  | History Up        | Browse previous message in terminal-style history navigation      |
| `↓`                  | History Down      | Browse next message in terminal-style history navigation          |

Note: Three detection methods for Option key on macOS:

1. `key.meta` property
2. Escape sequences `\x1bf` / `\x1bb`
3. Terminal.app default special characters `ƒ` / `∫`

## Text Deletion

### Readline Compatible Shortcuts

| Shortcut | Function                    | Description                               |
| -------- | --------------------------- | ----------------------------------------- |
| `Ctrl+K` | Delete to End of Line       | Delete from cursor to end of current line |
| `Ctrl+U` | Delete to Beginning of Line | Delete from beginning of line to cursor   |
| `Ctrl+W` | Delete Previous Word        | Delete the word before cursor             |
| `Ctrl+D` | Delete Character at Cursor  | Delete the character at cursor position   |

### Legacy Compatible Shortcuts (Preserved)

| Shortcut | Function           | Description                              |
| -------- | ------------------ | ---------------------------------------- |
| `Ctrl+L` | Clear to Beginning | Delete from beginning to cursor (legacy) |
| `Ctrl+R` | Clear to End       | Delete from cursor to end (legacy)       |

## Mode Switching

### YOLO and Plan Modes

| Shortcut    | Function    | Description                                      |
| ----------- | ----------- | ------------------------------------------------ |
| `Shift+Tab` | Cycle Modes | Cycle through: YOLO → YOLO+Plan → Plan → All Off |
| `Ctrl+Y`    | Cycle Modes | Same as `Shift+Tab`, cycle through modes         |

Mode switching sequence:

1. YOLO Mode
2. YOLO + Plan Mode (automatically disables Vulnerability Hunting when enabling Plan)
3. Plan Mode
4. All Off

### Profile Configuration Switching

| Shortcut | Function               | Platform        |
| -------- | ---------------------- | --------------- |
| `Ctrl+P` | Switch to Next Profile | macOS           |
| `Alt+P`  | Switch to Next Profile | Windows / Linux |

## Navigation and Selection

### Universal Navigation (All Pickers)

| Shortcut | Function          | Scope                                |
| -------- | ----------------- | ------------------------------------ |
| `↑`      | Previous Item     | All pickers (circular: first → last) |
| `↓`      | Next Item         | All pickers (circular: last → first) |
| `Enter`  | Confirm Selection | All pickers                          |
| `ESC`    | Close             | All pickers and panels               |

### File Picker Specific Shortcuts

| Shortcut       | Function            | Description                                                              |
| -------------- | ------------------- | ------------------------------------------------------------------------ |
| `@`            | Trigger File Picker | File list appears automatically after typing `@`                         |
| `@@`           | Content Search      | Search file contents instead of filenames                                |
| `@:` / `@@:`   | Workspace Filter    | Pick a working directory to scope search within, displays `@[tag]` label |
| `@??` / `@@??` | AI Agent Search     | Use AI agent to intelligently search for files based on natural language |
| `Tab`          | Select File         | Select the currently highlighted file in picker                          |
| `Space`        | Toggle Multi-Select | Check/uncheck current file for batch insertion                           |
| `Ctrl+T`       | Toggle Display Mode | Switch between tree and flat display modes                               |
| Type text      | Filter Files        | Supports filename and content search                                     |

File picker search modes:

- `@` — Filename fuzzy search across all working directories
- `@@` — Content search: find files by their contents (supports line numbers)
- `@:` / `@@:` — Workspace filter: type `:` after `@` or `@@` to pick a working directory from the list. After selecting, a `@[tag]` label is inserted into the input box and subsequent search is scoped to that directory only
- `@??` / `@@??` — AI agent search: type `??` after `@` or `@@` to trigger an AI-powered file search. The agent understands natural language queries and searches across working directories, streaming preview results in real time

### Command Panel Shortcuts

| Shortcut  | Function              | Description                                     |
| --------- | --------------------- | ----------------------------------------------- |
| `/`       | Trigger Command Panel | Available command list appears after typing `/` |
| `Tab`     | Auto-complete         | Replace input with selected command name        |
| Type text | Filter Commands       | Fuzzy search by command name and description    |

### Agent Picker

| Shortcut               | Function          | Description                                    |
| ---------------------- | ----------------- | ---------------------------------------------- |
| `/agent-` then `Enter` | Open Agent Picker | Select `agent-` command from command panel     |
| Type text              | Auto-filter       | Input automatically updates agent filter state |

### TODO Picker

| Shortcut              | Function                | Description                                                      |
| --------------------- | ----------------------- | ---------------------------------------------------------------- |
| `/todo-` then `Enter` | Open TODO Picker        | Select `todo-` command from command panel                        |
| `Space`               | Toggle Selection        | Select/deselect current TODO item                                |
| `Backspace`           | Delete Search Character | Remove last character from search query                          |
| Type text             | Search Filter           | Supports fuzzy search with multi-byte characters (Chinese, etc.) |

### Profile Picker

| Shortcut    | Function                | Description                                           |
| ----------- | ----------------------- | ----------------------------------------------------- |
| `Backspace` | Delete Search Character | Remove last character from search query               |
| Type text   | Fuzzy Search            | Filter profile list with multi-byte character support |

## Clipboard Operations

| Shortcut | Function | Platform                                   |
| -------- | -------- | ------------------------------------------ |
| `Ctrl+V` | Paste    | macOS (supports text and images)           |
| `Alt+V`  | Paste    | Windows / Linux (supports text and images) |

Note: Paste functionality supports:

- Plain text
- Images (auto-detection and image placeholder insertion)

## Command Execution Control

### Background Execution

| Shortcut   | Function                      | Description                                        |
| ---------- | ----------------------------- | -------------------------------------------------- |
| `Ctrl+B`   | Move command to background    | Only available during command execution            |
| `/backend` | Open background process panel | View and manage all commands running in background |

Background execution functionality notes:

- When a long-running command occupies the foreground, use `Ctrl+B` to move it to background
- Command continues executing in background without affecting your operations
- Use `/backend` command to view all background processes
- In background process panel:
  - `↑/↓` - Select process
  - `Enter` - Terminate selected running process
  - `ESC` - Close panel

## History and Rollback

### Double-ESC Rollback Menu

| Shortcut    | Function              | Description                                                              |
| ----------- | --------------------- | ------------------------------------------------------------------------ |
| `ESC` `ESC` | Open Rollback Menu    | Press ESC twice within 500ms                                             |
| `↑` / `↓`   | Select Rollback Point | Navigate in history messages to select rollback position                 |
| `Enter`     | Confirm Rollback      | Rollback to selected message point (shows confirmation if files changed) |
| `ESC`       | Close Rollback Menu   | Exit rollback mode                                                       |

Rollback functionality notes:

- If the selected rollback point has file changes, system will show file rollback confirmation dialog
- Supports selective rollback of partial files or full rollback
- Supports cross-session rollback (from compressed session to original session)
- After rollback, selected history message content will be restored to input box

### File Rollback Confirmation Dialog

When rollback point contains file changes, a confirmation dialog appears with fine-grained control:

| Shortcut  | Function              | Description                                                                                   |
| --------- | --------------------- | --------------------------------------------------------------------------------------------- |
| `Tab`     | Toggle View Mode      | Switch between compact mode and full file list mode                                           |
| `↑` / `↓` | Navigate              | Compact mode: select rollback option; Full mode: navigate file list                           |
| `Space`   | Toggle File Selection | Full mode only: select/deselect currently highlighted file                                    |
| `Enter`   | Confirm Action        | Compact mode: confirm selected option; Full mode: confirm file selection and execute rollback |
| `ESC`     | Back/Cancel           | Full mode: return to compact mode; Compact mode: cancel entire rollback operation             |

File selection mode:

- All files are selected by default
- Use `Space` to deselect files you don't want to rollback
- Deselecting all files is equivalent to "conversation only" rollback
- Partial selection will only rollback selected files
- Full mode displays file selection status: `[x]` selected, `[ ]` unselected

### Terminal-style History Navigation

| Shortcut | Function         | Description                                   |
| -------- | ---------------- | --------------------------------------------- |
| `↑`      | Previous History | When input box is empty or no panels are open |
| `↓`      | Next History     | Browse history records                        |

## Panels and Pickers

### Close Priority (ESC Key)

When pressing `ESC` key, the system closes panels in the following priority order:

1. Profile Picker
2. TODO Picker
3. Agent Picker
4. File Picker
5. Command Panel
6. History Menu

### Special Commands

| Command   | Function          | Description                             |
| --------- | ----------------- | --------------------------------------- |
| `/todo-`  | Open TODO Picker  | Select and manage TODO items in project |
| `/agent-` | Open Agent Picker | Select sub-agent to execute tasks       |

## Multi-byte Character Input Support

The system fully supports multi-byte input methods:

- All search and filter functions support multi-byte characters (Chinese, Japanese, Korean, etc.)
- Word boundary detection supports CJK punctuation (`\p{P}` Unicode property)
- Input method composition state is handled correctly to avoid triggering search for each letter

## Focus Event Filtering

The system automatically filters terminal focus events to prevent interference characters:

- Filters all possible focus events within 500ms after component mount
- Automatically recognizes and filters `ESC[I` (focus in) and `ESC[O` (focus out) sequences
- Supports focus events generated during drag-and-drop operations

## Tips

- Most navigation supports circular mode (returns to beginning after reaching end)
- Shortcut design follows Readline standards, familiar to bash/zsh users
- macOS and Windows/Linux differ in some shortcuts (mainly Ctrl vs Alt/Meta)
- All text input supports paste detection, can safely handle large text pastes