Keyboard-First Design

Maestro is designed for keyboard-first workflows. Every feature is accessible via keyboard shortcuts, and most operations never require touching the mouse.

Quick Reference

Press Cmd+/ at any time to view the shortcuts help modal. Modal: src/renderer/components/ShortcutsHelpModal.tsx

Essential Shortcuts

# Agent Switching
Cmd+[              # Previous agent
Cmd+]              # Next agent
Alt+Cmd+1-0        # Jump to agent 1-10 (0 = 10th)

# History Navigation
Cmd+Shift+,        # Navigate back
Cmd+Shift+.        # Navigate forward

# Focus Management
Cmd+.              # Toggle input/output focus
Cmd+Shift+A        # Focus Left Bar (agent list)
Cmd+Shift+F        # Focus Files tab
Cmd+Shift+H        # Focus History tab

Source: src/renderer/constants/shortcuts.ts:14-42

Agent Management

Creating
Organizing
Deleting

Cmd+N              # New agent (quick create)
Cmd+Shift+N        # New agent wizard (guided setup)
Alt+Cmd+C          # New group chat

Cmd+Shift+M        # Move agent to group
Cmd+Shift+B        # Toggle bookmark
Cmd+Shift+S        # Toggle tab star

Cmd+Shift+Backspace # Remove agent (with confirmation)

Tab Management (AI Mode)

# Tab Operations
Cmd+T              # New tab
Cmd+W              # Close current tab
Cmd+Shift+T        # Reopen closed tab
Cmd+Shift+W        # Close all tabs
Alt+Cmd+W          # Close other tabs

# Tab Navigation
Cmd+Shift+]        # Next tab
Cmd+Shift+[        # Previous tab
Cmd+1-9            # Jump to tab 1-9
Cmd+0              # Jump to last tab
Alt+Cmd+T          # Tab switcher modal

# Tab Management
Cmd+Shift+R        # Rename tab
Cmd+U              # Filter unread tabs
Cmd+Shift+U        # Toggle tab unread

Full tab shortcuts: src/renderer/constants/shortcuts.ts:125-178

Panel Toggles

# Left Bar (Agent List)
Alt+Meta+ArrowLeft # Toggle Left Bar
Cmd+Shift+A        # Focus Left Bar

# Right Bar (Files/History/Auto Run)
Alt+Meta+ArrowRight # Toggle Right Bar
Cmd+Shift+F        # Go to Files tab
Cmd+Shift+H        # Go to History tab
Cmd+Shift+1        # Go to Auto Run tab

Source: src/renderer/constants/shortcuts.ts:4-29

Git & Version Control

# Diff & Logs
Cmd+Shift+D        # View git diff
Cmd+Shift+G        # View git log

# File Preview
Cmd+P              # Copy file path (in preview)
Cmd+E              # Toggle edit/preview mode
Cmd+ArrowLeft      # File preview: Go back
Cmd+ArrowRight     # File preview: Go forward

Source: src/renderer/constants/shortcuts.ts:43-44, 112-121

Search & Filter

Maestro uses context-aware search: Cmd+F adapts based on what you’re viewing.

Main Window Search

Cmd+F              # Search AI output or terminal history

Context: When focused on main panel, searches the active conversation or terminal output.Source: src/renderer/constants/shortcuts.ts:102-106

File Explorer Filter

Cmd+F              # Filter files (in Files tab)
Cmd+G              # Fuzzy file search

Context: When Files tab is active, opens file tree filter.Source: src/renderer/constants/shortcuts.ts:90

Session Filter

Cmd+F              # Filter sessions (in Left Bar)

Context: When Left Bar is focused, filters agent list.Source: src/renderer/constants/shortcuts.ts:91-95

History Search

Cmd+F              # Filter history (in History tab)

Context: When History tab is active, searches conversation history.Source: src/renderer/constants/shortcuts.ts:96-100

Mode Switching

# Input Mode
Cmd+J              # Switch between AI/Shell mode

# Read-Only Mode (per tab)
Cmd+R              # Toggle read-only mode

# Save to History
Cmd+S              # Toggle save to history

# Thinking Display
Cmd+Shift+K        # Toggle show thinking

Source: src/renderer/constants/shortcuts.ts:22, 147-160

Quick Actions

The Quick Actions modal (Cmd+K) provides fuzzy search over all Maestro features:

Cmd+K              # Open Quick Actions

Available Actions:

Open settings
Create new agent
Toggle panels
View git diff/log
Launch wizards
System monitors
And more…

Modal: src/renderer/components/QuickActionsModal.tsx

Advanced Features

System Monitors

Cmd+Shift+L        # View agent sessions
Alt+Cmd+L          # System log viewer
Alt+Cmd+P          # Process monitor
Alt+Cmd+U          # Usage dashboard

Source: src/renderer/constants/shortcuts.ts:45-56

Auto Run

Cmd+Shift+1        # Go to Auto Run tab
Cmd+Shift+E        # Toggle Auto Run expanded view
Alt+Cmd+S          # Toggle auto-scroll

Source: src/renderer/constants/shortcuts.ts:29, 36-40, 71-75

Special Modals

Cmd+,              # Open settings
Alt+Cmd+,          # Open agent settings
Cmd+/              # Show shortcuts help
Cmd+Shift+P        # Open prompt composer
Cmd+Shift+Y        # Maestro Symphony
Cmd+Shift+O        # Director's Notes

Source: src/renderer/constants/shortcuts.ts:24-26, 62-80

Cmd+Shift+J        # Jump to bottom of output
Cmd+Y              # Open image carousel

Source: src/renderer/constants/shortcuts.ts:57-60

Customizing Shortcuts

All configurable shortcuts can be edited in Settings → Keyboard Shortcuts.

Open Settings

Press Cmd+, to open the Settings modal.

Navigate to Shortcuts

Click the Keyboard Shortcuts tab.

Edit a Shortcut

Click any shortcut row to record a new key combination.

Reset to Defaults

Click Reset All to restore default shortcuts.

Component: src/renderer/components/ShortcutEditor.tsx

Non-Editable Shortcuts

Some shortcuts are fixed and cannot be customized:

// From src/renderer/constants/shortcuts.ts:84-122
export const FIXED_SHORTCUTS: Record<string, Shortcut> = {
  jumpToSession: {
    label: 'Jump to Session (1-9, 0=10th)',
    keys: ['Alt', 'Meta', '1-0'],
  },
  filterFiles: {
    label: 'Filter Files (in Files tab)',
    keys: ['Meta', 'f'],
  },
  // ... context-aware Cmd+F shortcuts
}

These are context-aware and adapt based on UI state.

Shortcut Format

Shortcuts are defined in a structured format:

// From src/renderer/constants/shortcuts.ts:1-81
export const DEFAULT_SHORTCUTS: Record<string, Shortcut> = {
  toggleSidebar: {
    id: 'toggleSidebar',
    label: 'Toggle Left Panel',
    keys: ['Alt', 'Meta', 'ArrowLeft'],
  },
  // ...
}

Key Modifiers:

Meta = Cmd on macOS, Ctrl on Windows/Linux
Alt = Option on macOS
Shift = Shift key

Formatting: src/renderer/utils/shortcutFormatter.ts

Platform Differences

Maestro adapts shortcuts for each platform:

Modifier	macOS	Windows/Linux
`Meta`	`Cmd`	`Ctrl`
`Alt`	`Option`	`Alt`
`Shift`	`Shift`	`Shift`

Some shortcuts may conflict with OS-level bindings on Linux. Check Settings → Keyboard Shortcuts to customize.

Tips for Keyboard Efficiency

Learn Incrementally

Start with these 5 shortcuts:

Cmd+K - Quick Actions (discover features)
Cmd+J - Toggle AI/Terminal
Cmd+[ / Cmd+] - Switch agents
Cmd+T - New tab
Cmd+/ - View all shortcuts

Use Quick Actions

Don’t memorize every shortcut. Press Cmd+K and type what you want to do. Quick Actions shows the associated keyboard shortcut for future reference.

Context-Aware Cmd+F

Cmd+F works everywhere but does different things based on context. Learn to use it reflexively:

Main window → Search output
Files tab → Filter files
Left Bar → Filter agents
History tab → Search history

Focus Management

Master Cmd+. to toggle between input and output. This lets you scroll output with keyboard (arrow keys, Page Up/Down) without leaving the keyboard.

Complete Shortcut List

View the full shortcut reference by pressing Cmd+/ or visiting: Settings → Keyboard Shortcuts The shortcuts help modal groups shortcuts by category:

Global - App-wide shortcuts
Navigation - Agent and tab switching
Panels - Toggle sidebars and views
Git - Version control shortcuts
Auto Run - Batch processing
System - Monitors and logs
Tab Management - AI tab operations

Next Steps

Agent Management

Learn multi-agent orchestration

Dual-Mode Sessions

Switch between AI and terminal

Output Filtering

Search and filter output efficiently

Git Integration

Version control workflows

Get Started

Core Features

Power Features

Analytics

Keyboard-First Design

Quick Reference

Essential Shortcuts

Navigation

Agent Management

Tab Management (AI Mode)

Panel Toggles

Git & Version Control

Search & Filter

Mode Switching

Quick Actions

Advanced Features

System Monitors

Auto Run

Special Modals

Output Navigation

Customizing Shortcuts

Non-Editable Shortcuts

Shortcut Format

Platform Differences

Tips for Keyboard Efficiency

Complete Shortcut List

Next Steps

Agent Management

Dual-Mode Sessions

Output Filtering

Git Integration

Build docs developers (and LLMs) love

Get Started

Core Features

Power Features

Analytics

​Quick Reference

​Essential Shortcuts

​Navigation

​Agent Management

​Tab Management (AI Mode)

​Panel Toggles

​Git & Version Control

​Search & Filter

​Mode Switching

​Quick Actions

​Advanced Features

​System Monitors

​Auto Run

​Special Modals

​Output Navigation

​Customizing Shortcuts

​Non-Editable Shortcuts

​Shortcut Format

​Platform Differences

​Tips for Keyboard Efficiency

​Complete Shortcut List

​Next Steps

Agent Management

Dual-Mode Sessions

Output Filtering

Git Integration

Build docs developers (and LLMs) love

Quick Reference

Essential Shortcuts

Navigation

Agent Management

Tab Management (AI Mode)

Panel Toggles

Git & Version Control

Search & Filter

Mode Switching

Quick Actions

Advanced Features

System Monitors

Auto Run

Special Modals

Output Navigation

Customizing Shortcuts

Non-Editable Shortcuts

Shortcut Format

Platform Differences

Tips for Keyboard Efficiency

Complete Shortcut List

Next Steps