General Usage

​

UI Overview

Maestro features a three-panel layout:

• Left Panel - Agent list with grouping, filtering, search, bookmarks, and drag-and-drop organization
• Main Panel - Center workspace with two modes per agent:
  • AI Terminal - Converse with your AI provider (Claude Code, Codex, or OpenCode). Supports multiple tabs (each tab is a session), @ file mentions, image attachments, slash commands, and draft auto-save.
  • Command Terminal - PTY shell with tab completion for files, branches, tags, and command history.
  • Views: Session Explorer, File Preview, Git Diffs, Git Logs
• Right Panel - Three tabs: File Explorer, History Viewer, and Auto Run

​

Agent Status Indicators

Each agent shows a color-coded status indicator:

• 🟢 Green - Ready and waiting
• 🟡 Yellow - Agent is thinking
• 🔴 Red - No connection with agent
• 🟠 Pulsing Orange - Attempting to establish connection
• 🔴 Red Badge - Unread messages (small red dot overlapping top-right of status indicator, iPhone-style)

​

File Explorer and Preview

The File Explorer (Right Panel → Files tab) lets you browse project files. Click any file to open it in the File Preview view. File Preview features:

• Syntax highlighting for code files
• Markdown rendering with toggle between raw/preview (Cmd+E / Ctrl+E)
• Image viewing for common image formats
• Line numbers for easy reference
• Search within file (Cmd+F / Ctrl+F)

​

Breadcrumb Navigation

When you open a file, a breadcrumb trail appears showing your navigation history. Click any breadcrumb to jump back to a previously viewed file. This makes it easy to compare files or return to where you were.

​

File Editing

Files can be edited directly in the preview. Changes are saved automatically when you navigate away or close the preview.

​

Publish as GitHub Gist

Share files directly as GitHub Gists from the File Preview: Prerequisites:

• GitHub CLI (gh) must be installed
• You must be authenticated (gh auth login)

To publish a file:

1. Open a file in File Preview
2. Click the Share icon (↗) in the header toolbar, or
3. Use Cmd+K / Ctrl+K → “Publish Document as GitHub Gist”

Visibility options: The confirmation modal focuses “Publish Secret” by default, so you can press Enter to quickly publish. Press Esc to cancel. After publishing:

• The gist URL is automatically copied to your clipboard
• A toast notification appears with a link to open the gist in your browser

​

@ File Mentions

Reference files in your AI prompts using @ mentions:

1. Type @ followed by a filename
2. Select from the autocomplete dropdown
3. The file path is inserted, giving the AI context about that file

​

Prompt Composer

For complex prompts that need more editing space, use the Prompt Composer — a fullscreen editing modal. To open the Prompt Composer:

• Click the pencil icon (✏️) in the bottom-left corner of the AI input box

The Prompt Composer provides:

• Full-screen editing space for complex, multi-paragraph prompts
• Character and token count displayed in the footer
• All input controls — History toggle, Read-only mode, Thinking toggle, and send shortcut indicator
• Image attachment support via the image icon in the footer

When you’re done editing, click Send or press the displayed shortcut to send your message. The composer closes automatically and your prompt is sent to the AI.

​

Input Toggles

The AI input box includes three toggle buttons that control session behavior: Per-tab persistence: Each toggle state is saved per tab. If you enable Thinking on one tab, it stays enabled for that tab even when you switch away and back.

​

Configuring Defaults

Set the default state for new tabs in Settings (Cmd+, / Ctrl+,) → General:

​

Send Key Configuration

Configure how messages are sent in each mode:

• When set to Cmd+Enter / Ctrl+Enter, pressing Enter alone creates a new line (for multi-line input)
• When set to Enter, use Shift+Enter for new lines
• The current send key is displayed in the input box (e.g., ”⌘ + Enter”)
• Per-tab override: Click the send key indicator in the input box to toggle between modes for that tab

​

Image Carousel

When working with image attachments, use the Image Carousel to view, manage, and remove images. To open the Image Carousel:

• Press Cmd+Y / Ctrl+Y, or
• Click the image icon in the input box when images are attached

Carousel controls:

• Arrow keys — Navigate between images
• Delete or Backspace — Remove the currently selected image
• Click the X — Remove an image by clicking its remove button
• Esc — Close the carousel

Images can be attached via drag-and-drop, paste, or the attachment button. The carousel shows all images queued for the current message.

​

Output Filtering

Filter and search through AI output to find specific content or hide noise.

​

Global Filter

The global filter applies to all AI output in the current session. To open the global filter:

• Click the filter icon in the output toolbar
• The filter bar appears at the top of the output area

​

Per-Response Filters

Each AI response has its own local filter. Hover over a response to reveal the filter icon, then click to open the filter bar for that specific response.

​

Filter Modes

Click the mode icon to toggle between Include and Exclude.

​

Text vs Regex Matching

Click the indicator to toggle between plain text and regex mode.

​

Filter Controls

• Query input — Type your search term or regex pattern
• Esc — Clear the filter and close the filter bar
• Click outside — If the query is empty, the filter bar closes

​

Placeholders

The placeholder text updates to reflect the current mode:

• “Include by keyword” / “Exclude by keyword” for plain text
• “Include by RegEx” / “Exclude by RegEx” for regex mode

​

Use Cases

Finding specific content:

• Set to Include mode with plain text
• Type a keyword like “error” or “function”
• Only matching lines are shown

Hiding verbose output:

• Set to Exclude mode with plain text
• Type patterns like “debug” or “verbose”
• Matching lines are hidden from view

Complex pattern matching:

• Enable Regex mode
• Use patterns like \berror\b for word boundaries
• Or ^\s*# to match comment lines

​

Command Interpreter

The command interpreter can be focused for a clean, terminal-only experience when you collapse the left panel.

​

Agent Management

Agents are the core of Maestro — each agent represents an AI coding assistant running in its own workspace.

​

Creating Agents

To create a new agent:

1. Press Cmd+N / Ctrl+N, or click the + button in the left panel
2. Select an available AI provider (Claude Code, Codex, or OpenCode)
3. Choose a working directory for the agent
4. Optionally name the agent and configure advanced options

Advanced configuration options:

• Nudge Message — An initial prompt sent when the agent starts
• Custom Path — Override the default executable path
• Custom Arguments — Additional command-line arguments
• Environment Variables — Custom environment variables for the agent process
• Model Selection — Choose a specific model (if the provider supports it)

​

Editing Agents

Right-click any agent in the left panel and select Edit Agent… to modify its configuration. You can change the name, nudge message, custom paths, arguments, environment variables, and model.

​

Deleting Agents

Right-click an agent and select Remove Agent to delete it. This removes the agent from Maestro but does not delete any files or AI session data.

​

Agent Configuration via Quick Actions

Use Cmd+K / Ctrl+K → “Edit Agent” to quickly access agent configuration for the current session.

​

Left Panel Operations

The left panel (sidebar) contains your agent list, groups, and navigation controls.

​

Filtering and Search

Press Cmd+F / Ctrl+F while the sidebar is focused to open the session filter. The filter:

• Searches agent names and AI tab names
• Automatically expands groups containing matches
• Shows matching bookmarked agents
• Searches worktree branch names

​

Bookmarks

Pin important agents to the top of the list:

• Right-click an agent → Add Bookmark
• Or use the context menu to toggle bookmark status

Bookmarked agents appear in a collapsible “Bookmarks” section at the top of the left panel.

​

Groups

Organize agents into groups for better project management: Creating groups:

• Cmd+K / Ctrl+K → “Create Group”
• Groups have a name and emoji for visual identification

Moving agents to groups:

• Right-click an agent → Move to Group → Select target group
• Or drag-and-drop agents between groups

Collapsing/Expanding:

• Click the group header to collapse or expand
• Groups remember their collapsed state

​

Drag and Drop

Rearrange agents by dragging them:

• Drag agents between groups
• Drag to reorder within a group
• Drag to the “Ungrouped” section to remove from a group

​

Context Menu

Right-click any agent for quick actions:

• Rename — Change the agent’s display name
• Edit Agent… — Open configuration modal
• Add/Remove Bookmark — Toggle bookmark status
• Move to Group — Organize into groups
• Create Worktree — Create a git worktree sub-agent (if configured)
• Configure Worktrees — Set up worktree configuration
• Remove Agent — Delete the agent from Maestro

​

Sidebar Width

Drag the right edge of the sidebar to resize it. The width is persisted across sessions.

​

Collapsed Mode

Click the sidebar toggle (Cmd+B / Ctrl+B) to collapse the sidebar to icon-only mode. In collapsed mode:

• Agents show as icons with status indicators
• Hover for agent name tooltip
• Click to select an agent

​

Session Management

Browse, star, rename, and resume past sessions. The Session Explorer (Cmd+Shift+L / Ctrl+Shift+L) shows all conversations for an agent with search, filtering, and quick actions.