Maestro

Orchestrate multiple AI coding assistants in parallel

A native macOS application that lets you run 1-12 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! 🙏😊

---

📖 Table of Contents

• 🎯 Why Maestro?
• ✨ Features
• 🏗️ Architecture
• 📦 Installation
• 🚀 Usage
• ⚙️ Configuration
• 🔧 Troubleshooting
• 🤝 Contributing
• 📄 License
• 🙏 Acknowledgments

---

🎯 Why Maestro?

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

Core Principles

Principle	Description
Parallel Development	Launch 1-12 AI sessions simultaneously. Work on feature branches, bug fixes, and refactoring all at once.
True Isolation	Each session operates in its own git worktree. No merge conflicts, no stepping on each other's changes.
AI-Native Workflow	Built specifically for Claude Code, Gemini CLI, OpenAI Codex, and other AI coding assistants.

---

✨ Features

Multi-Terminal Session Grid

• Dynamic grid layout (1x1 to 3x4) that adapts to your session count
• Real-time status indicators: idle, working, waiting for input, done, error
• Per-session mode selection (Claude Code, Gemini CLI, OpenAI Codex, Plain Terminal)

Git Worktree Isolation

• 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

MCP Server Integration

• 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

Visual Git Graph

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

Template Presets

• Save session configurations (modes, branches, count)
• Quickly load common workflows
• Persist across app restarts

Quick Actions

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

Multi-AI Support

• 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

Plugin Marketplace

• 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

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Claude Maestro (Swift/SwiftUI)               │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Session 1   │  │  Session 2   │  │  Session 3   │   ...    │
│  │ Claude Code  │  │ Gemini CLI   │  │  Terminal    │          │
│  │ feature/auth │  │ fix/bug-123  │  │    main      │          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
│         │                 │                 │                   │
│  ┌──────▼─────────────────▼─────────────────▼───────┐          │
│  │              WorktreeManager                      │          │
│  │     ~/.claude-maestro/worktrees/{repo}/{branch}  │          │
│  └──────────────────────────────────────────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ MCP Protocol (stdio)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  MaestroMCPServer (Swift)                       │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                     StatusManager                           ││
│  │  maestro_status tool - agents report their current state    ││
│  │  (idle, working, needs_input, finished, error)              ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

Technology Stack

Component	Technology
Desktop App	Swift 5.9, SwiftUI, AppKit
Terminal Emulator	SwiftTerm
MCP Server	Swift MCP SDK (agent status reporting)
Git Operations	Native git CLI

---

📦 Installation

Requirements

• macOS 13 (Ventura) or later
• Xcode 15 or later
• Claude Code CLI (npm install -g @anthropic-ai/claude-code)

Build from Source

1. Clone the repository:

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

2. Open in Xcode:

   open claude-maestro.xcodeproj

3. Build and run (⌘R)

The Swift MCP server (MaestroMCPServer/) is built automatically as part of the Xcode build process.

4. Configure MCP (optional):

   cp .mcp.json.example .mcp.json

   Edit .mcp.json and update the command path to point to your built MaestroMCPServer binary (typically found at ~/Library/Application Support/Claude Maestro/MaestroMCPServer after first run).

Optional: Install AI CLIs

# 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

---

🚀 Usage

Quick Start

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-12)
   • 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

Session Management

• 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

Git Worktree Isolation

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

Template Presets

Save your session configurations:

1. Configure sessions as desired
2. Click "Save Preset" in the sidebar
3. Name your preset (e.g., "Feature Development", "Bug Triage")
4. Load presets from the dropdown to restore configurations

Quick Actions

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

---

⚙️ Configuration

Session Persistence

Session configurations (modes, branches, count) are automatically persisted to UserDefaults and restored on app launch.

Debug Logging

For troubleshooting git operations, you can enable debug logging:

# Enable debug logging
defaults write com.maestro.claude-maestro debug-git-logging -bool true

# Disable debug logging
defaults write com.maestro.claude-maestro debug-git-logging -bool false

When enabled, git command logs are written to ~/maestro-debug.log.

---

🔧 Troubleshooting

Claude Command Not Found

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

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

Worktree Issues

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

---

🤝 Contributing

Development Setup

1. Fork and clone the repository
2. Open claude-maestro.xcodeproj in Xcode
3. Make your changes
4. Test thoroughly with multiple sessions

Project Structure

claude-maestro/
├── claude-maestro/              # Swift/SwiftUI macOS app
│   ├── ContentView.swift        # Main view and session management
│   ├── TerminalView.swift       # SwiftTerm integration
│   ├── WorktreeManager.swift    # Git worktree management
│   ├── GitManager.swift         # Git operations
│   ├── GitTreeView.swift        # Commit graph visualization
│   └── ...
├── MaestroMCPServer/            # Swift MCP server
│   ├── Sources/
│   │   └── MaestroMCPServer/    # MCP tool implementations
│   └── Package.swift
└── README.md

Code Style

• Follow Apple's Swift API Design Guidelines

---

📄 License

MIT License - see LICENSE for details.

---

🙏 Acknowledgments

• SwiftTerm - Terminal emulator for Swift
• Model Context Protocol - MCP SDK
• Claude Code - AI coding assistant

---

Built with Love by Jack