diff --git a/docs/tui/keyboard-shortcuts.md b/docs/tui/keyboard-shortcuts.md new file mode 100644 index 00000000..87788dbf --- /dev/null +++ b/docs/tui/keyboard-shortcuts.md @@ -0,0 +1,412 @@ +# CAI TUI Keyboard Shortcuts + +> **⚡ CAI-Pro Exclusive Feature** +> The Terminal User Interface (TUI) is available exclusively in **CAI-Pro**. To access this feature and unlock advanced multi-agent workflows, visit [Alias Robotics](https://aliasrobotics.com) for more information. + +--- + +Master the CAI TUI with these keyboard shortcuts for maximum productivity. All shortcuts work across different terminal operating systems. + + +## Navigation Shortcuts + +### Sidebar + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+S` | Toggle sidebar | Opens/closes the sidebar panel | + +**Usage**: +- Quick access to Teams, Queue, Stats, and Keys +- Sidebar state persists during session +- Width: 32 characters when open + +**Alternative**: Click the `☰` button in the top-left corner + +--- + +### Terminal Navigation + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+N` | Next terminal | Cycles forward through terminals (1→2→3→4→1) | +| `Ctrl+B` | Previous terminal | Cycles backward through terminals (1→4→3→2→1) | + +**Usage**: +- Focus moves to the next/previous terminal +- Visual indicator shows active terminal +- Works even when sidebar is open + +**Alternative**: Click directly on any terminal to focus it + +--- + +### Tab Navigation + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+Tab` | Next tab | Cycles through Terminal → CTR → Help → Terminal | +| `Ctrl+1` | Terminal tab | Jump directly to Terminal tab | +| `Ctrl+2` | CTR tab | Jump directly to CTR (graph) tab | + +**Usage**: +- Switch between main views instantly +- Terminal tab: Main workspace with agents +- CTR tab: Visual graph of agent relationships +- Help tab: Built-in documentation + +**Alternative**: Click tab names in the top bar + +## Terminal Management + +### Opening Terminals + +| Shortcut | Action | Details | +|----------|--------|---------| +| Click `+` button | Add terminal | Creates new terminal with default settings | +| `/add` command | Add terminal | Command-based terminal creation | + +**Default Settings**: +- Agent: `redteam_agent` +- Model: `alias1` +- Container: `local` + +--- + +### Closing Terminals + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+E` | Close current terminal | Closes the focused terminal | +| `/remove T` | Close specific terminal | Example: `/remove T3` | + +**Notes**: +- Terminal 1 cannot be closed (main terminal) +- Closing removes conversation history (save with `/save` first) +- Remaining terminals re-layout automatically + +--- + +### Clearing Terminals + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+L` | Clear all terminals | Removes output from all terminal screens | +| `/clear` | Clear current terminal | Command to clear focused terminal only | + +**Notes**: +- Only clears visual output, not conversation history +- Use `/flush` to clear conversation history + +## Execution Control + +### Canceling Agents + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+C` | Cancel current agent | Stops the agent in the focused terminal | +| `ESC` | Cancel all agents | Stops all running agents across all terminals | + +**When to Use**: +- Agent is taking too long +- Wrong prompt was sent +- Need to interrupt for corrections +- Agent is stuck in a loop + +**Effect**: +- Agent stops immediately +- Partial output remains visible +- Can send new prompt right away + +--- + +### Parallel Execution + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+Shift+A` | Prompt all agents | Sends the current input to all active terminals in parallel | + +**Usage Flow**: +1. Type your prompt in the input field +2. Press `Ctrl+Shift+A` instead of `Enter` +3. All terminals receive and process the prompt simultaneously + +**Use Cases**: +- Multi-perspective analysis (red team + blue team) +- Bug bounty triage with multiple agents +- Comprehensive security assessment + +**Alternative**: Use `/parallel` commands for more control + +Learn more: [Teams and Parallel Execution](teams-and-parallel-execution.md) + +## Utility Shortcuts + +### Command Palette + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+P` | Open command palette | Textual's command palette for searching actions | + +**Features**: +- Search available commands +- Quick access to any action +- Fuzzy search support + +--- + +### Queue Management + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+Shift+Q` | Show queue | Displays the current prompt queue in main terminal | + +**Alternative Commands**: +- `/queue` - Show queue +- `/queue add ` - Add to queue +- `/queue remove N` - Remove item N +- `/queue clear` - Clear queue + +Learn more: [Commands Reference - Queue Management](commands-reference.md#queue-management) + +--- + +### Theme Cycling + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+Shift+T` | Cycle themes | Switches between available color themes | + +**Available Themes**: +- Dark (default teal theme) +- Light +- Textual Dark +- Textual Light + +**Alternative**: Set `CAI_THEME` environment variable + +Learn more: [User Interface - Themes](user-interface.md#themes) + +--- + +### Clearing Input + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+U` | Clear input | Removes all text from the input field | + +**Usage**: +- Quick way to start fresh +- Clear accidental text +- Standard Unix/Linux behavior + +--- + +### Exit Application + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+Q` | Exit CAI TUI | Closes the application completely | + +**Alternative**: Click the `×` button in top-right corner + +**On Exit**: +- Session summary displayed (costs, tokens, duration) +- Unsaved conversations are lost (use `/save` first) +- API keys and configuration persist + +## Input Editing + +### Command Autocompletion + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Tab` | Autocomplete | Completes the current command or shows suggestions | + +**Examples**: +- Type `/ag` + `Tab` → `/agent` +- Type `/mod` + `Tab` → `/model` +- Type `/para` + `Tab` → `/parallel` + +**Behavior**: +- Single match: Completes automatically +- Multiple matches: Shows list of suggestions +- No match: No action + +--- + +### Command History + +| Shortcut | Action | Details | +|----------|--------|---------| +| `↑` (Up Arrow) | Previous command | Navigate backward through command history | +| `↓` (Down Arrow) | Next command | Navigate forward through command history | + +**Features**: +- History persists across sessions +- Stored in `~/.cai/history` +- Includes both commands and prompts +- Maximum history size: 1000 entries + +**Usage Flow**: +1. Press `↑` to recall previous command +2. Continue pressing `↑` to go further back +3. Press `↓` to move forward in history +4. Edit recalled command if needed +5. Press `Enter` to execute + +--- + +### Command Suggestions + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+Space` | Show suggestions | Displays available commands matching current input | + +**Usage**: +- Type partial command +- Press `Ctrl+Space` +- Select from suggested commands + +**Suggestion Categories**: +- `/agent` commands +- `/model` commands +- `/parallel` commands +- `/queue` commands +- Other commands + +--- + +### Send Prompt + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Enter` | Send prompt/command | Executes the current input | + +**Behavior**: +- Commands (starting with `/`): Execute immediately +- Prompts: Send to current agent +- If agent is busy: Automatically queued + +## Terminal Content Copying + +### Copy Visible Content + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+Shift+X` | Copy visible | Copies currently visible terminal content to clipboard | + +**Use Cases**: +- Share specific output with team +- Save important findings +- Document tool results + +--- + +### Copy All Content + +| Shortcut | Action | Details | +|----------|--------|---------| +| `Ctrl+Shift+Z` | Copy all | Copies entire terminal content (including scrolled) to clipboard | + +**Use Cases**: +- Complete session documentation +- Comprehensive reporting +- Full conversation export + +**Alternative**: Use `/save` command for structured export to file + +## Platform-Specific Notes + +### macOS + +All shortcuts work as documented. Some terminals (e.g., Terminal.app) may require: +- Enabling "Use Option as Meta key" in preferences +- Allowing keyboard shortcuts in Security & Privacy settings + +### Linux + +All shortcuts work as documented. If using tmux/screen: +- `Ctrl+B` conflicts with tmux prefix → Consider remapping tmux +- `Ctrl+S` may freeze terminal → Disable XON/XOFF with `stty -ixon` + +### Windows + +All shortcuts work in Windows Terminal and modern terminals. In older terminals: +- Some `Ctrl+Shift+` combinations may not work +- Use command alternatives (e.g., `/queue` instead of `Ctrl+Shift+Q`) + +## Custom Shortcuts + +CAI TUI currently does not support custom keyboard shortcuts. This feature may be added in future versions. + +**Workaround**: Use command aliases or shell scripts for custom workflows. + +## Tips for Efficiency + +### Power User Workflow + +1. **Keep sidebar closed** (`Ctrl+S`) for max screen space +2. **Use `Ctrl+N`/`Ctrl+B`** to switch terminals instead of mouse +3. **Master `Tab` completion** for faster command input +4. **Use `↑`** to repeat similar prompts with modifications +5. **Leverage `Ctrl+Shift+A`** for parallel team analysis + +### Recommended Shortcuts to Memorize First + +Priority 1 (Essential): +- `Ctrl+S` - Toggle sidebar +- `Ctrl+Q` - Exit +- `Ctrl+C` - Cancel agent +- `Enter` - Send prompt +- `Tab` - Autocomplete + +Priority 2 (Common): +- `Ctrl+N` / `Ctrl+B` - Navigate terminals +- `Ctrl+L` - Clear screen +- `↑` / `↓` - Command history +- `ESC` - Cancel all + +Priority 3 (Advanced): +- `Ctrl+Shift+A` - Parallel prompt +- `Ctrl+E` - Close terminal +- `Ctrl+Shift+Q` - Show queue +- `Ctrl+P` - Command palette + +## Troubleshooting Shortcuts + +### Shortcut Not Working? + +**Check 1: Terminal Compatibility** +- Some shortcuts may be intercepted by your terminal emulator +- Check terminal preferences for keyboard settings +- Try a different terminal (e.g., Alacritty, iTerm2) + +**Check 2: tmux/screen Conflicts** +- tmux uses `Ctrl+B` as prefix (conflicts with "Previous Terminal") +- screen uses `Ctrl+A` as prefix (no conflicts with CAI TUI) +- Consider remapping tmux prefix: `set -g prefix C-a` + +**Check 3: OS-Level Shortcuts** +- Some OS keyboard shortcuts override terminal shortcuts +- Example: macOS `Ctrl+Shift+Space` opens Spotlight +- Disable conflicting OS shortcuts or use command alternatives + +### Accidental Exit (`Ctrl+Q`) + +If you frequently press `Ctrl+Q` by accident: + +**Workaround**: Use the `/exit` or `/quit` command instead + +**Future Feature**: Exit confirmation dialog (planned) + +## See Also + +- 🎯 [Commands Reference](commands-reference.md) - All available commands +- 🖥️ [User Interface](user-interface.md) - Visual guide to the interface +- 📖 [Getting Started](getting-started.md) - Basic usage tutorial + +--- + +*Last updated: October 2025 | CAI TUI v0.6+* +