Maestro

Multi-agent orchestrator for Claude Code, Codex, Qwen, OpenCode, Ollama, and MiniMax — with a Matrix-style terminal control center.

Landing page: carlosdanieldev.github.io/maestro (features · quickstart) — static shell, no build step (site source).

Maestro spawns and monitors multiple AI agent sessions working on the same project simultaneously. Mix providers — run Claude, Codex, Qwen, OpenCode, Ollama, and MiniMax side by side, or pick one per session. It provides real-time visibility into what each session is doing, how much it's spending, and coordinates their work to prevent conflicts — all from a single TUI dashboard.

Most deep guides live in the project Wiki. This README is the on-ramp.

Important: if you run maestro against a Claude Pro/Max subscription, set transport = "interactive" on your claude agent in maestro.toml before 2026-06-15 — Anthropic withdraws subscription billing from headless claude --print on that date. See the transport guide.

Features

Session orchestration

• Multi-session pool — run up to N concurrent agent sessions with automatic queue promotion
• Interaction sessions — chat with the agent working your issue in a live transcript, with PR auto-detection (guide)
• Git worktree isolation per session prevents file conflicts
• File claim registry blocks two sessions from editing the same file simultaneously
• Full session state machine (QUEUED → SPAWNING → RUNNING → GATES_RUNNING → COMPLETED / NEEDS_REVIEW / ERRORED / PAUSED / KILLED)
• State and costs persisted to maestro-state.json for recovery and reporting

→ Wiki › Sessions and Pool

TUI dashboard

• Interactive landing screen with quick-actions menu, contextual work suggestions, and recent activity
• DOS-style F-key status bar (F1 Help, F2 Summary, F3 Full, F4 Costs, F5 Tokens, F6 Deps, F9 Pause, F10 Kill, Ctrl+X Exit)
• Rich activity log — file paths, command previews, tool durations, extended-thinking markers
• Status-transition flash on session state changes
• Completion-summary overlay when all sessions finish
• Nerd-font icons throughout

→ Wiki › TUI Dashboard · Home and Landing Screens

GitHub & Azure DevOps integration

• Multi-provider — auto-detected from the git remote, or set explicitly in [provider]
• Issue browser and milestone overview directly inside the TUI
• Issue/Milestone wizards for guided launches
• Label lifecycle: maestro:ready → maestro:in-progress → maestro:done / maestro:failed
• Dependency scheduling via blocked-by:#N labels and body references; priority ordering via priority:P0/P1/P2
• Automated PR creation on session completion with cost report and file list; PR URL logged to the activity log on success; existing-PR detection skips duplicate creation and surfaces the existing URL
• PR Review automation with optional bypass mode

→ Wiki › Multi-Provider (GitHub & Azure) · PR Review Automation · Issue and Milestone Wizards

Quality & autonomy

• maestro doctor preflight checks — verifies enabled agent providers, gh/az, and git before spending API credits
• Configurable completion gates (fmt / clippy / test or any custom command) run after every session; failures of required gates block PR creation
• Language-aware session prompt guardrails (Rust / TS / Python / Go) auto-injected, overridable via guardrail_prompt
• Continuous mode (--continuous / -C) auto-advances through ready issues with a pause overlay on failure
• Context-overflow auto-fork with structured handoff prompts and configurable fork-depth limit
• Smart retry policies on transient errors

→ Wiki › Doctor and Preflight · Completion Gates · Context Overflow and Forking · Milestone Mode and Continuous

Power features

• TurboQuant context compression (PolarQuant + QJL residual) with a runtime toggle via Ctrl+q
• Cost and token dashboards with per-session and total spend tracking
• Self-upgrade with automatic backup and restart confirmation
• Shell completions (bash / zsh / fish) and a man page in every release
• Desktop and Slack notifications

→ Wiki › TurboQuant Compression · Cost and Token Dashboards · Self-Upgrade · Notifications

Agent providers

• Multi-agent runtime — Claude, Codex, Qwen, OpenCode, Ollama, and MiniMax can be configured side by side in [agents]
• Subprocess providers — Claude, Codex, Qwen, and OpenCode run local CLIs
• HTTP providers — Ollama and MiniMax stream through HTTP APIs
• Claude remains the default when [agents] is omitted

→ Docs › Agent Providers · Configuration Reference · Example multi-agent config

Team orchestration (v0.26.0+)

• Five built-in team presets — default-coder, default-researcher, default-triager, default-reviewer, default-docs — wired to coordination primitives (pipeline, fan-out, single-pass, verdict-only)
• Three-tier preset resolution: built-in → user (~/.config/maestro/maestro/teams/) → project (<repo>/.maestro/teams/)
• Headless launch — maestro team launch <preset> --issue N --yes drives the scheduler to completion for CI / scripting; per-issue failures surface as a non-zero exit
• Inspect resolved bindings with maestro team explain <name>; manage user-tier presets with maestro team manage --list

→ Docs › Team Orchestration

Requirements

• Rust 1.89+ (edition 2024)
• At least one agent provider: Claude Code CLI (claude) by default, or another configured provider from [agents]
• GitHub CLI (gh) — required when using the GitHub provider (default)
• Azure CLI (az) — required when using the Azure DevOps provider; run az login to authenticate
• macOS, Linux, or WSL

Install

Homebrew (macOS and Linux)

brew tap CarlosDanielDev/tap
brew install carlosdanieldev/tap/maestro --formula

Note: The --formula flag is required because an unrelated cask named "maestro" exists in Homebrew core.

Pre-built binary

Download the tarball for your platform from the latest GitHub Release, extract it, and place the maestro binary on your PATH.

Platform	Archive
macOS (Apple Silicon)	maestro-<version>-aarch64-apple-darwin.tar.gz
macOS (Intel)	maestro-<version>-x86_64-apple-darwin.tar.gz
Linux (x86_64)	maestro-<version>-x86_64-unknown-linux-gnu.tar.gz

A sha256sums.txt file is included for checksum verification.

From source

git clone https://github.com/CarlosDanielDev/maestro.git
cd maestro
cargo build --release
# Binary at target/release/maestro

Updating

Maestro checks for new versions on startup and shows an in-TUI banner — press [u] to upgrade with automatic backup and restart confirmation. You can also run brew upgrade carlosdanieldev/tap/maestro --formula (Homebrew) or git pull && cargo build --release (source).

→ Wiki › Self-Upgrade

Quick Start

maestro init                                              # interactive maestro.toml setup
maestro init --non-interactive                            # headless GitHub defaults
maestro doctor                                            # verify gh/az/agent CLI/git
maestro run --prompt "Refactor the auth module to async"  # ad-hoc session
maestro run --issue 42                                    # session for a GitHub issue
maestro run --milestone "v1.0"                            # all open issues in a milestone
maestro                                                   # open the TUI dashboard

For the full command catalogue see Wiki › CLI Reference or run maestro --help.

Configuration

Maestro reads maestro.toml from the project root. Run maestro init to generate it — the command auto-detects your project's tech stack (Rust, Node, Python, Go, or polyglot), detects the provider from origin, and prompts you to confirm GitHub or Azure DevOps. Azure DevOps setup asks for the organization URL and project name, then persists the required experimental opt-in. Use maestro init --non-interactive for headless/CI setup; it skips remote detection and prompts, and writes GitHub provider defaults. Run maestro init --reset to re-detect and merge results into an existing file (existing keys are preserved).

A minimal maestro.toml:

[project]
repo        = "owner/repo"
base_branch = "main"

[sessions]
max_concurrent = 3            # parallel agent sessions
default_model  = "opus"       # opus | sonnet | haiku
default_mode   = "orchestrator"

[budget]
per_session_usd     = 5.0
total_usd           = 50.0
alert_threshold_pct = 80      # warn at 80% of budget

[github]
auto_pr = true

[provider]
kind = "github"
issue_filter_labels = ["maestro:ready"]
auto_pr = true
auto_merge = false
merge_method = "squash"
cache_ttl_secs = 300

Multi-agent setup

Claude is still the default when [agents] is absent. To add explicit agent providers, define [agents] and one table per provider. Use --agent <id> for one run or change [agents].default for the project.

[agents]
default = "claude"

[agents.claude]
kind = "claude"
enabled = true
command = "claude"
model = "opus"

[agents.codex]
kind = "codex"
enabled = false
command = "codex"
model = "gpt-5.4-codex"
sandbox = "workspace-write"
json = true

[agents.qwen]
kind = "qwen"
enabled = false
command = "qwen"
model = "qwen-test"
extra_args = ["--auth-type", "openai"]

[agents.opencode]
kind = "opencode"
enabled = false
command = "opencode"
model = "openrouter/deepseek/deepseek-chat"

[agents.ollama]
kind = "ollama"
enabled = false
model = "qwen3"
base_url = "http://localhost:11434"
request_timeout_secs = 120

[agents.minimax]
kind = "minimax"
enabled = false
model = "MiniMax-M2.7"
base_url = "https://api.minimax.io/v1"
request_timeout_secs = 120
api_key_env = "MINIMAX_API_KEY"

Subprocess providers (claude, codex, qwen, opencode) require a local CLI command. HTTP providers (ollama, minimax) require base_url and use request_timeout_secs for API calls.

maestro run --prompt "Refactor the auth module to async" --agent codex
maestro run --issue 42 --agent ollama
maestro doctor

See Docs › Agent Providers for setup guides, migration notes, and troubleshooting for all supported providers.

Azure DevOps init writes kind = "azure_devops", organization, az_project, and [experimental] azure_devops = true.

The full schema — agent providers, completion gates, context-overflow tuning, TurboQuant, provider/Azure DevOps configuration, notifications, and feature flags — is documented in Docs › Configuration Reference and Wiki › Configuration Reference.

Architecture

See directory-tree.md for the full source layout. At a high level:

1. src/cli.rs parses the command and dispatches to a handler.
2. The session pool spawns agent subprocesses (claude by default, or any configured provider — Codex, Qwen, OpenCode; Ollama and MiniMax stream over HTTP), each in an isolated git worktree, parsing their streamed output.
3. The ratatui TUI renders the pool state, activity log, and dashboards from a shared in-memory store persisted to maestro-state.json.

→ Wiki › Architecture

GitHub Label System

Maestro reads and writes a small set of GitHub labels to coordinate work. All names are defined in src/provider/github/types.rs.

Label	Purpose
maestro:ready	Queued and ready for a session to pick up (managed)
maestro:in-progress	A session is currently working on this issue (managed)
maestro:done	Session completed successfully and PR was opened (managed)
maestro:failed	Session ended with an error (managed)
priority:P0 / P1 / P2	Scheduling priority — P0 first (set by you)
mode:orchestrator / mode:vibe	Run session in the named mode (set by you)
blocked-by:#N	Issue cannot start until #N closes (also accepted in body)

Keyboard Shortcuts

The full key map (global, overview, home screen, issue browser, milestone overview, prompt input) is at Wiki › Keyboard Shortcuts.

Shell Completions

Maestro ships pre-generated bash, zsh, and fish completions plus a maestro.1 man page in every release tarball; Homebrew installs them automatically. To regenerate on demand: maestro completions <bash|zsh|fish>. Per-shell installation paths and zsh fpath configuration are covered in Wiki › Installation.

Template sync

Maestro ships canonical command specs in .maestro/templates/commands/. The maestro sync-templates subcommand renders those specs per provider and writes them to the correct target directory (e.g. .claude/commands/ for Claude Code). Rendered files carry an AUTO-GENERATED banner and must not be edited directly — edit the canonical source and re-render.

maestro sync-templates                     # render all providers
maestro sync-templates --provider claude   # render Claude only
maestro sync-templates --check            # verify no drift (what CI runs)
maestro sync-templates --dry-run          # preview writes without touching files

SHA-256 checksums of every rendered file are recorded in .maestro/templates.lock (committed). The CI pipeline fails if any rendered output diverges from its canonical source.

Integration with .claude/

When you run the Claude provider, Maestro wraps — not replaces — your existing .claude/ agent system. Each spawned Claude session inherits your project's CLAUDE.md, agents, skills, and commands. Maestro adds coordination context (file claims, peer awareness) via --append-system-prompt. Other providers read their own equivalent files (.codex/AGENTS.md, AGENTS.md, GEMINI.md) — maestro sync-templates keeps command specs rendered per provider.

Roadmap

ROADMAP.md is the single source of truth for shipped and upcoming work; CHANGELOG.md has detailed release notes. The latest release is v0.30.0 (interactive iteration sessions — kept-alive chat over the real session pipeline, multi-provider follow-up turns, native in-session diff reviewer). Browse open milestones at github.com/CarlosDanielDev/maestro/milestones; the latest released binary is always at releases/latest.

Contributing

Contributions are welcome. The full developer guide lives in Wiki › Contributing.

Quick orientation:

cargo build           # debug build
cargo test            # run tests
cargo clippy && cargo fmt    # lint and format

The Rust coding policy — error handling, async discipline, unsafe, testing, dependencies, style — is in docs/RUST-GUARDRAILS.md. The .claude/ directory hosts the orchestrator-mode agent system; see .claude/CLAUDE.md for the workflow rules.

License

MIT