maestro

Orchestrate multiple AI coding assistants in parallel

A cross-platform desktop application that lets you run 1-6 Claude Code (or other AI CLI) sessions simultaneously, each in its own isolated git worktree.

Star us on GitHub — your support motivates us a lot!

• Why Maestro?
• Features
• Keyboard Shortcuts
• Architecture
• Installation
• Usage
• Configuration
• Troubleshooting
• Contributing
• License
• Acknowledgments

The Problem: AI coding assistants work on one task at a time. While Claude works on Feature A, you wait. Then you start Feature B. Then you wait again. Context switching is expensive, and your development velocity is bottlenecked by serial execution.

The Solution: Run multiple AI sessions in parallel. Each session gets its own:

• Terminal instance with full shell environment
• Git worktree for complete code isolation
• Assigned branch for focused work
• Port allocation for web development

• Dynamic grid layout (1x1 to 2x3) that adapts to your session count
• iTerm2-style split panes within each session (Cmd+D vertical, Cmd+Shift+D horizontal)
• Real-time status indicators: idle, working, waiting for input, done, error
• Per-session mode selection (Claude Code, Gemini CLI, OpenAI Codex, Plain Terminal)

• Automatic worktree creation at ~/.claude-maestro/worktrees/
• Each session works on its own branch without conflicts
• Worktrees are pruned on session close
• Visual branch assignment in the sidebar
• "Worktree" badge in the terminal header when a session is running in a worktree

• Built-in MCP server for agent status reporting
• AI sessions report their state (idle, working, needs input, finished, error)
• Real-time status updates displayed in the session grid
• Uses the maestro_status tool for state communication

• GitKraken-style commit visualization
• Branch relationship view with colored rails
• Commit detail panel with diffs
• See which sessions are working on which branches

• Custom action buttons per session
• "Run App", "Commit & Push", and custom prompts
• Execute commands via AI assistant

• Light and dark theme support
• Terminal font customization with support for:
  • System-installed fonts
  • Nerd Fonts (icons and glyphs)
  • Custom fonts
• Adjustable text size for terminal display

• Claude Code - Anthropic's Claude in the terminal
• Gemini CLI - Google's Gemini AI
• OpenAI Codex - OpenAI's coding assistant
• Plain Terminal - Standard shell without AI

• Browse and install plugins from marketplace sources
• Plugin types: Skills, Commands, and MCP servers
• Per-session plugin configuration
• Automatic symlink management for commands and skills
• Extend Maestro's capabilities with community plugins

Note: Cmd = Ctrl on Windows/Linux

┌─────────────────────────────────────────────────────────────────┐
│                    Claude Maestro (Tauri)                       │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Session 1   │  │  Session 2   │  │  Session 3   │   ...    │
│  │ Claude Code  │  │ Gemini CLI   │  │  Terminal    │          │
│  │ feature/auth │  │ fix/bug-123  │  │    main      │          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
│         │                 │                 │                   │
│  ┌──────▼─────────────────▼─────────────────▼───────┐          │
│  │              ProcessManager (Rust)               │          │
│  │     ~/.claude-maestro/worktrees/{repo}/{branch}  │          │
│  └──────────────────────────────────────────────────┘          │
│                                                                 │
│  Frontend: React + TypeScript + Tailwind CSS                    │
│  Backend: Rust + Tauri                                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ MCP Protocol (stdio)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MCP Server (Rust)                            │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                     StatusManager                           ││
│  │  maestro_status tool - agents report their current state    ││
│  │  (idle, working, needs_input, finished, error)              ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

• Node.js 18+ and npm
• Rust 1.78+ (for building from source) - install via rustup, not system packages
• Git (for worktree operations)

macOS (13 Ventura or later):

# Install Xcode Command Line Tools
xcode-select --install

Windows (10 or later):

• Install Visual Studio Build Tools with the "Desktop development with C++" workload
• Install Rust
• WebView2 Runtime is required (pre-installed on Windows 10 21H2+ and Windows 11; download here for older versions)

Linux (Ubuntu 24.04 LTS / Debian):

# Install Rust via rustup (Ubuntu 24.04's apt packages ship Rust 1.75, which is too old)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# Install required system dependencies
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev \
  libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev \
  libfontconfig1-dev patchelf

Note: On Ubuntu 24.04, use libayatana-appindicator3-dev instead of libappindicator3-dev to avoid package conflicts.

Linux (Fedora):

sudo dnf install gcc-c++ pkg-config openssl-devel \
  webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel

Linux (Arch):

sudo pacman -S base-devel pkgconf openssl \
  webkit2gtk-4.1 libappindicator-gtk3 librsvg

1. Clone the repository:

   git clone https://github.com/its-maestro-baby/maestro.git
   cd maestro

2. Install npm dependencies:

   npm install

3. Build the MCP server:

   cargo build --release -p maestro-mcp-server

   This builds the Rust MCP server binary that Tauri bundles with the application.

4. Run in development mode:

   npm run tauri dev

5. Build for production:

   npm run tauri build

   The built application will be in src-tauri/target/release/bundle/.

# Claude Code (recommended)
npm install -g @anthropic-ai/claude-code

# Gemini CLI
npm install -g @google/gemini-cli

# OpenAI Codex
npm install -g @openai/codex

1. Launch Claude Maestro
2. Select a project directory (ideally a git repository)
3. Configure sessions in the sidebar:
   • Set the number of terminals (1-6)
   • Choose AI mode for each session
   • Assign branches to sessions
4. Click "Launch" to start all sessions
5. Each session opens in its own worktree with the AI ready to work

• Add sessions: Click the floating + button
• Close sessions: Click the × on the session header
• Change mode: Use the mode dropdown in the session header
• Assign branch: Select from the branch dropdown

When you assign a branch to a session:

1. Maestro creates a worktree at ~/.claude-maestro/worktrees/{repo-hash}/{branch}
2. The session's terminal opens in that worktree
3. All file changes are isolated to that worktree
4. Worktrees are cleaned up when sessions close

Each session can have quick action buttons:

• Run App - Tells the AI to run the application
• Commit & Push - Tells the AI to commit and push changes
• Custom - Configure your own prompts

Copy the example configuration and update paths:

cp .mcp.json.example .mcp.json

Edit .mcp.json to configure the MCP server for agent status reporting.

The Claude CLI must be installed globally and in your PATH:

npm install -g @anthropic-ai/claude-code
which claude  # Should show the path

If worktrees get into a bad state:

# List all worktrees
git worktree list

# Remove a specific worktree
git worktree remove /path/to/worktree --force

# Prune stale worktree entries
git worktree prune

If you encounter build issues:

# Clear all Rust build caches
rm -rf src-tauri/target
rm -rf maestro-mcp-server/target

# Clear node modules and reinstall
rm -rf node_modules
npm install

# Rebuild MCP server first, then Tauri app
cargo build --release -p maestro-mcp-server
npm run tauri build

1. Fork and clone the repository
2. Install npm dependencies: npm install
3. Build the MCP server: cargo build --release -p maestro-mcp-server
4. Run in dev mode: npm run tauri dev
5. Make your changes
6. Test thoroughly with multiple sessions

maestro/
├── src/                     # React/TypeScript frontend
│   ├── components/          # UI components
│   ├── lib/                 # Utility libraries
│   └── App.tsx              # Main application
├── src-tauri/               # Tauri Rust backend
│   ├── src/
│   │   ├── commands/        # Tauri command handlers
│   │   ├── core/            # Core business logic
│   │   └── lib.rs           # Main Rust entry point
│   ├── Cargo.toml           # Rust dependencies
│   └── tauri.conf.json      # Tauri configuration
├── maestro-mcp-server/      # Rust MCP server (bundled with app)
│   ├── src/
│   │   └── main.rs          # MCP server entry point
│   └── Cargo.toml           # MCP server dependencies
├── Cargo.toml               # Workspace configuration
├── package.json             # Node.js dependencies
└── README.md

MIT License - see LICENSE for details.

• Tauri - Cross-platform desktop framework
• xterm.js - Terminal emulator for the web
• Model Context Protocol - MCP SDK
• Claude Code - AI coding assistant

Built with Love by Jack