maestro-orchestrate

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)
Maestro does not edit ~/.gemini/settings.json or ~/.qwen/settings.json for you.
Installation
Gemini CLI
Local development:
Verify with gemini extensions list.
Claude Code
Marketplace install:
Development / temporary loading:
More Claude-specific setup and plugin management lives in claude/README.md.
Codex
Register the marketplace:
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):
More Codex-specific setup and runtime details live in plugins/maestro/README.md and docs/runtime-codex.md.
Qwen Code
Local development:
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 |