Maestro

Maestro is a multi-agent development orchestration platform with 39 specialists, an Express path for simple work, a 4-phase standard workflow for medium and complex work, persistent session state, and standalone review/debug/security/perf/seo/accessibility/compliance entrypoints. It runs from one canonical src/ tree across Gemini CLI, Claude Code, Codex, and Qwen Code.

Runtime Targets

Runtime	Location	Public Surface	Notes
Gemini CLI	repo root	/maestro:*	Snake-case agents, TOML commands, hooks, TOML shell policies
Claude Code	claude/	/orchestrate, /review-code, ...	Kebab-case agents with maestro: subagent names
Codex	plugins/maestro/	$maestro:*	Plugin skills, spawn_agent, no runtime hooks
Qwen Code	qwen/	/maestro:*	Gemini-CLI-compatible extension, QWEN.md context file, SubagentStart/SubagentStop hooks

Getting Started

Prerequisites

• One supported runtime: Gemini CLI, Claude Code, Codex, or Qwen Code
• Node.js 20+ for the MCP server and helper scripts
• Gemini CLI and Qwen Code only: enable experimental subagents in ~/.gemini/settings.json (Gemini) or ~/.qwen/settings.json (Qwen)

{
  "experimental": {
    "enableAgents": true
  }
}

Maestro does not edit ~/.gemini/settings.json or ~/.qwen/settings.json for you.

Installation

Gemini CLI

gemini extensions install https://github.com/josstei/maestro-orchestrate

Local development:

git clone https://github.com/josstei/maestro-orchestrate
cd maestro-orchestrate
gemini extensions link .

Verify with gemini extensions list.

Claude Code

Marketplace install:

claude plugin marketplace add josstei/maestro-orchestrate
claude plugin install maestro@maestro-orchestrator --scope user

Development / temporary loading:

git clone https://github.com/josstei/maestro-orchestrate
claude --plugin-dir /path/to/maestro-orchestrate/claude

More Claude-specific setup and plugin management lives in claude/README.md.

Codex

Register the marketplace:

codex plugin marketplace add josstei/maestro-orchestrate

Then start Codex, run /plugins to browse, select Maestro, and choose Install.

Local development (path must start with ./, ../, /, or ~/ — Codex otherwise treats bare owner/repo as a GitHub source):

git clone https://github.com/josstei/maestro-orchestrate
codex plugin marketplace add /absolute/path/to/maestro-orchestrate
# then: start Codex, run `/plugins`, select Maestro → Install

More Codex-specific setup and runtime details live in plugins/maestro/README.md and docs/runtime-codex.md.

Qwen Code

qwen extensions install https://github.com/josstei/maestro-orchestrate

Local development:

git clone https://github.com/josstei/maestro-orchestrate
cd maestro-orchestrate
qwen extensions link .

Verify with qwen extensions list. Qwen Code uses the same /maestro:* command surface as Gemini CLI and reads QWEN.md as its context file.

Quick Start

Start a full orchestration with the runtime-specific entrypoint:

Runtime	Example
Gemini CLI	/maestro:orchestrate Build a REST API for a task management system with user authentication
Claude Code	/orchestrate Build a REST API for a task management system with user authentication
Codex	$maestro:orchestrate Build a REST API for a task management system with user authentication
Qwen Code	/maestro:orchestrate Build a REST API for a task management system with user authentication

Maestro classifies the task, chooses Express or Standard workflow, asks the required design questions, produces an implementation plan when needed, delegates execution to specialists, runs a quality gate, and archives the session state in docs/maestro/.

Examples

Usage examples: EXAMPLES.md. Gemini/Qwen forms shown:

• Full orchestration: /maestro:orchestrate Build a REST API for a task management system with user authentication
• Standalone review: /maestro:review Review the staged changes for correctness, regressions, security, maintainability risk, and missing tests
• Security audit: /maestro:security-audit Audit authentication, authorization, data exposure, secret handling, and exploitability risks

Configuration

Defaults work; these settings tune behavior:

Setting	Default	Purpose
MAESTRO_STATE_DIR	docs/maestro	Session, plan, and archive output path
MAESTRO_EXECUTION_MODE	ask	Choose parallel, sequential, or prompt
MAESTRO_AUTO_ARCHIVE	true	Archive successful sessions automatically
MAESTRO_MAX_RETRIES	2	Retry limit for failed phases
MAESTRO_MAX_CONCURRENT	0	Parallel-agent cap, where 0 means no Maestro cap
MAESTRO_DISABLED_AGENTS	unset	Specialists to exclude from assignment

Commands

Capability	Gemini CLI	Claude Code	Codex	Qwen Code
Orchestrate	/maestro:orchestrate	/orchestrate	$maestro:orchestrate	/maestro:orchestrate
Execute	/maestro:execute	/execute	$maestro:execute	/maestro:execute
Resume	/maestro:resume	/resume-session	$maestro:resume-session	/maestro:resume
Status	/maestro:status	/status	$maestro:status	/maestro:status
Archive	/maestro:archive	/archive	$maestro:archive	/maestro:archive
Review	/maestro:review	/review-code	$maestro:review-code	/maestro:review
Debug	/maestro:debug	/debug-workflow	$maestro:debug-workflow	/maestro:debug
Security Audit	/maestro:security-audit	/security-audit	`$maestro:security