Maestro Documentation

Maestro is a cross-platform desktop application designed to orchestrate multiple AI coding assistants (such as Claude Code, Gemini CLI, or OpenAI Codex) in parallel. It allows you to run 1-6 simultaneous sessions, each isolated within its own Git worktree to prevent merge conflicts and context switching.

Key capabilities include:

• Multi-Terminal Session Grid: A dynamic layout for managing multiple AI sessions.
• Git Worktree Isolation: Automatic creation and pruning of worktrees at ~/.claude-maestro/worktrees/ to ensure code isolation.
• MCP Server Integration: Uses a built-in Model Context Protocol (MCP) server to report agent status (idle, working, needs input, finished, error) via the maestro_status tool.
• Multi-AI Support: Native support for Claude Code, Gemini CLI, OpenAI Codex, and standard terminal shells.

Maestro's UI is organized into a Sidebar and a Main Content Area.

Sidebar Tabs:

• Config Tab: Manage presets, terminal counts, session lists, status overviews, Git info, the CLAUDE.md editor, MCP status, the marketplace, quick actions, and themes.
• Processes Tab: Monitor Agent status cards, manage dev servers (start/stop/restart), view filtered output streams, and clean up orphaned processes.

Main Content Area:

• ProjectTabs (Workspace): Manages multiple project tabs.
• PreLaunchView: Shown during setup.
• TerminalGrid (Active): Displays active terminal sessions in a grid. Each terminal cell includes a header bar with a status indicator, mode picker, branch picker, quick action buttons, and a close button.

Maestro is a cross-platform desktop application built with a Tauri (Rust) backend and a React/TypeScript frontend. It is designed to orchestrate multiple AI coding assistants in parallel.

Project Layout

• src/: The React/TypeScript frontend. Contains UI components (Git, Marketplace, Terminal, etc.), custom React hooks, utility libraries, and Zustand state stores.
• src-tauri/: The Tauri Rust backend.
  • src-tauri/src/commands/: Contains Tauri command handlers (the bridge between frontend and backend).
  • src-tauri/src/core/: Contains core business logic and managers (Process, Plugin, MCP, etc.).
• maestro-mcp-server/: A standalone Rust-based Model Context Protocol (MCP) server.
• website/: The project's documentation website.
• docs/: Additional research and specification documentation.

Maestro includes a built-in MCP server that runs as a sidecar process communicating over stdio. This server enables real-time communication between AI agents and the Maestro UI.

Key Capabilities:

• Agent status reporting: AI sessions use the maestro_status tool to report their state.
• State tracking: The UI tracks five specific states: idle, working, needs_input, finished, and error.
• Input prompts: When an agent requires user intervention, the prompt is displayed directly in the Maestro UI.

Maestro uses Git worktrees to allow multiple AI agents to work on the same repository simultaneously without file lock conflicts.

The Workflow:

1. Storage: Worktrees are stored in ~/.claude-maestro/worktrees/<repo-hash>/<branch-name>.
2. Creation:
   • The system checks if the target branch is currently checked out in the main repository.
   • If it is, the main repository is forced to switch to a default branch (like main or master) to free up the branch.
   • It then executes git worktree add <path> <branch>.
3. Binding: The session's workingDirectory is set to this new isolated path.
4. Cleanup: To prevent disk clutter, Maestro performs aggressive cleanup by running git worktree remove and deleting the directory when a session is closed or the app exits.

Maestro uses a combination of the following mechanisms to ensure that parallel AI sessions do not interfere with each other:

• Git Worktrees: Each session operates in its own isolated git worktree, providing a complete code isolation where each AI works on its own branch in its own copy of the codebase.
• Terminal Instances: Each session runs in its own terminal instance with a full shell environment.
• Port Allocation: Maestro manages port allocation to allow web development to occur simultaneously across different sessions.
• Assigned Branches: Each session is tied to a specific branch for focused work.

Maestro allows you to run 1–6 AI coding assistants simultaneously in a dynamic grid layout. The grid automatically adjusts from a 1x1 to a 2x3 layout based on the number of active sessions.

Each session provides:

• Independent terminals: A full terminal with its own shell environment.
• Real-time status indicators: Visual feedback on the session state: idle, working, waiting for input, done, or error.
• Per-session mode selection: You can assign different AI assistants to different slots in the grid.

Skills are reusable prompt definitions that the Agent can invoke. They are injected per-session rather than being global, allowing you to toggle them for specific chat sessions.

Discovery Locations

• ~/.claude/skills/ (User personal)
• ~/.claude/plugins/*/skills (Inside installed plugins)
• Project-local .claude/skills/

Defining a Skill

Skills are defined in SKILL.md files using YAML frontmatter:

name: example_skill
description: A description of what the skill does
allowed-tools: [Read, Grep]
argument-hint: Provide the filename to analyze

Session Injection

Maestro uses syncWorktreeSkills(worktreePath, sessionId) to create symbolic links in the target project's .claude/skills/ directory pointing to the installed skill location.

Hooks allow plugins to intercept Agent lifecycle events. They are aggregated into the project's .claude/settings.local.json during session injection.

Supported Event Types

• PreToolUse
• PostToolUse
• SessionStart
• SessionEnd
• UserPromptSubmit
• Stop

Configuration (hooks.json)

Plugins define hooks in a hooks.json file. Each hook maps an event type to:

• Matchers: Filters to restrict the hook to a specific tool or path.
• Actions: Either a command (to run a shell command) or a prompt (to inject text).

During injection, ${CLAUDE_PLUGIN_ROOT} is resolved in command/prompt strings before being written to the project settings.

Maestro visualizes AI agent activity using a file-based polling mechanism rather than direct socket communication.

Mechanism

1. Storage: The Agent writes state to a JSON file in the temporary directory: /tmp/maestro/agents/<agent-<sessionId>.json.
2. Monitoring: The MaestroStateMonitor polls this directory every 0.5 seconds.

AgentState Model

The JSON file follows the AgentState schema:

• state: Enum (idle, working, needs_input, finished, error).
• message: A human-readable description of the current status.
• needsInputPrompt: A specific question provided if the state is needs_input.
• timestamp: ISO 8601 timestamp (used to detect stale states older than 5 minutes).