Skip to main content

​
Overview

Maestro is a keyboard-first desktop application for managing multiple AI coding assistants simultaneously. This guide covers the essential workflows and usage patterns.

​
Application Layout

Maestro’s interface is divided into three main areas: Left Bar (agents), Main Window (workspace), and Right Bar (context).

​
UI Components

  • Left Bar - Agent list with groups and navigation
  • Main Window - AI Terminal or Command Terminal workspace
  • Right Bar - Files, History, and Auto Run tabs
  • System Log Viewer - Special view for system logs

​
Core Workflows

​
Creating Agents

1

Open New Agent Modal

Press Cmd+N (macOS) or Ctrl+N (Windows/Linux) to open the new agent modal.
2

Select Agent Type

Choose from supported agents:
  • Claude Code - Anthropic’s coding assistant
  • OpenCode - Open-source coding agent
  • Codex - OpenAI’s code assistant
  • Factory Droid - Specialized agent
3

Configure Settings

Set the workspace directory and optional custom configuration:
  • Custom binary path
  • Custom arguments
  • Environment variables

​
Agent Modes

Each agent operates in one of two modes:
AI Terminal - Interact directly with the AI agent
  • Multi-tab support for conversation organization
  • Read-only mode to prevent modifications
  • YOLO mode for unconfirmed operations
  • Session history and context management
  • Automatic tab naming based on conversation
Switch modes: Press Cmd+J to toggle between AI and Shell mode.

​
Working with Tabs

Tabs are only available in AI mode and help organize different conversation threads.
Common tab operations: 
Cmd+T          # New tab
Cmd+W          # Close current tab
Cmd+Shift+[    # Previous tab
Cmd+Shift+]    # Next tab
Cmd+Shift+T    # Reopen closed tab
Cmd+Shift+R    # Rename tab
Cmd+Shift+S    # Star/bookmark tab
Agent Navigation: 
Cmd+[          # Previous agent
Cmd+]          # Next agent
Alt+Cmd+1-0    # Jump to agent 1-10
Cmd+Shift+A    # Focus left panel
History Navigation: 
Cmd+Shift+,    # Navigate back
Cmd+Shift+.    # Navigate forward

​
Panel Management

Toggle panels: 
Alt+Cmd+←      # Toggle left panel
Alt+Cmd+→      # Toggle right panel
Cmd+Shift+F    # Go to Files tab
Cmd+Shift+H    # Go to History tab
Cmd+Shift+1    # Go to Auto Run tab

​
Agent States

Agents are color-coded by their current state:
  • 🟢 Green - Ready/idle, waiting for input
  • 🟡 Yellow - Agent thinking/busy, processing request
  • 🔴 Red - No connection/error state
  • 🟠 Pulsing Orange - Connecting to agent

​
Keyboard-First Design

Maestro is optimized for keyboard navigation. Press Cmd+/ to view all available shortcuts.

​
Essential Shortcuts

ShortcutAction
Cmd+KQuick Actions menu
Cmd+/Show all shortcuts
Cmd+,Open Settings
Alt+Cmd+,Open Agent Settings
Cmd+.Toggle Input/Output focus
Cmd+Shift+JJump to bottom

​
Quick Actions

Press Cmd+K to open the Quick Actions menu for common operations:
  • Create new agent
  • Switch between agents
  • Open settings
  • Toggle panels
  • Navigate to tabs
  • View system information

​
Best Practices

Create agent groups to organize related projects:
  • Press Cmd+Shift+M to move agent to group
  • Collapse/expand groups in the left panel
  • Groups persist across sessions
Enable read-only mode (Cmd+R) when you want the agent to analyze without making changes:
  • Safe code review
  • Architecture discussions
  • Documentation generation
Use the /history slash command to generate work summaries:
  • Automatic synopsis generation
  • Searchable history entries
  • Context for future sessions
Press Cmd+Shift+S to star tabs you want to keep:
  • Prevents accidental closure
  • Quick visual reference
  • Organizes important conversations

​
Settings Persistence

All settings are automatically persisted to disk. Changes to preferences, shortcuts, themes, and agent configurations are saved immediately.
Settings are stored in platform-specific locations:
  • macOS: ~/Library/Application Support/maestro/
  • Linux: ~/.config/maestro/
  • Windows: %APPDATA%\maestro\

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us