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 Antigravity, Claude Code, Codex, and Qwen Code.
| Runtime | Location | Public Surface | Notes |
|---|---|---|---|
| Antigravity | antigravity/ |
/maestro:* |
Plugin skills, kebab-case subagents run with invoke_subagent, SessionStart and run_command policy hooks |
| 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 | repo root + qwen/hooks.json |
/maestro:* |
Snake-case agents, TOML commands, QWEN.md context file, SubagentStart/SubagentStop hooks |
- One supported runtime: Antigravity (the
agyCLI or the Antigravity app), Claude Code, Codex, or Qwen Code - Node.js 20+ for the MCP server and helper scripts
agy plugin install https://github.com/josstei/maestro-orchestrate/tree/main/antigravityRestart agy afterwards: Antigravity discovers a newly installed plugin only on startup. Verify with agy plugin list.
Local development (link the plugin directory, then restart agy; a linked plugin loads but is not listed by agy plugin list):
git clone https://github.com/josstei/maestro-orchestrate
mkdir -p ~/.gemini/config/plugins
ln -s "$PWD/maestro-orchestrate/antigravity" ~/.gemini/config/plugins/maestroMore Antigravity-specific setup and runtime details live in antigravity/README.md and docs/runtime-antigravity.md.
Marketplace install:
claude plugin marketplace add josstei/maestro-orchestrate
claude plugin install maestro@maestro-orchestrator --scope userDevelopment / temporary loading:
git clone https://github.com/josstei/maestro-orchestrate
claude --plugin-dir /path/to/maestro-orchestrate/claudeMore Claude-specific setup and plugin management lives in claude/README.md.
Register the marketplace:
codex plugin marketplace add josstei/maestro-orchestrateThen 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 → InstallMore Codex-specific setup and runtime details live in plugins/maestro/README.md and docs/runtime-codex.md.
qwen extensions install https://github.com/josstei/maestro-orchestrateLocal development:
git clone https://github.com/josstei/maestro-orchestrate
cd maestro-orchestrate
qwen extensions link .Verify with qwen extensions list. Qwen Code reads QWEN.md as its context file and loads the /maestro:* commands from commands/maestro/*.toml.
Start a full orchestration with the runtime-specific entrypoint:
| Runtime | Example |
|---|---|
| Antigravity | /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/.
Usage examples: EXAMPLES.md. Qwen Code 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
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_VALIDATION_STRICTNESS |
normal |
Post-phase validation strictness (strict, normal, or lenient) |
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 |
| Capability | Antigravity | Claude Code | Codex | Qwen Code |
|---|---|---|---|---|
| Orchestrate | /maestro:orchestrate |
/orchestrate |
$maestro:orchestrate |
/maestro:orchestrate |
| Execute | /maestro:execute |
/execute |
$maestro:execute |
/maestro:execute |
| Resume | /maestro:resume-session |
/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-code |
/review-code |
$maestro:review-code |
/maestro:review |
| Debug | /maestro:debug-workflow |
/debug-workflow |
$maestro:debug-workflow |
/maestro:debug |
| Security Audit | /maestro:security-audit |
/security-audit |
$maestro:security-audit |
/maestro:security-audit |
| Performance Check | /maestro:perf-check |
/perf-check |
$maestro:perf-check |
/maestro:perf-check |
| SEO Audit | /maestro:seo-audit |
/seo-audit |
$maestro:seo-audit |
/maestro:seo-audit |
| Accessibility Audit | /maestro:a11y-audit |
/a11y-audit |
$maestro:a11y-audit |
/maestro:a11y-audit |
| Compliance Check | /maestro:compliance-check |
/compliance-check |
$maestro:compliance-check |
/maestro:compliance-check |
For Claude Code and Codex, Maestro intentionally avoids bare skill names that collide with host commands. Use /review-code, /debug-workflow, and /resume-session in Claude Code, and $maestro:review-code, $maestro:debug-workflow, and $maestro:resume-session in Codex, so built-in /review, /debug, and /resume commands keep working.
Antigravity has a built-in /resume, so it uses the same remapped names under its plugin namespace: /maestro:review-code, /maestro:debug-workflow, and /maestro:resume-session.
Qwen Code does not remap any entry point; it keeps /maestro:review, /maestro:debug, and /maestro:resume.
- Express: For simple work. Maestro asks 1-2 clarifying questions, proposes a brief, delegates to one specialist, runs code review, and archives without a design doc or implementation plan.
- Standard: For medium and complex work. Maestro runs Design, Plan, Execute, and Complete phases with explicit approval gates, phased execution, and final review blocking on unresolved Critical or Major findings.
Maestro writes orchestration outputs under MAESTRO_STATE_DIR, usually docs/maestro/. Standard workflow outputs include active session state, design documents, implementation plans, phase reports, validation output, and archived records.
A successful run must have an approved plan when Standard workflow is used, completed phase reports, validation results for the changed surface, and no unresolved Critical or Major review findings. If a phase cannot complete, Maestro records the blocker and the next required action instead of silently continuing.
Maestro follows the host runtime's tool permissions, sandboxing, and confirmation model. It does not require committed secrets or long-lived credentials, and orchestration session state stays inside MAESTRO_STATE_DIR unless configured otherwise. Use MAESTRO_DISABLED_AGENTS to restrict specialists in sensitive repositories, and run $maestro:security-audit or the equivalent runtime command before adopting changes that touch authentication, authorization, secrets, or data exposure paths.
- EXAMPLES.md for copyable usage scenarios across all runtimes
- docs/overview.md for the project model and generated structure
- docs/architecture.md for orchestration internals and architecture layout
- docs/usage.md for development workflow, settings, and command surfaces
- docs/flow.md for the orchestration workflow steps and hard gates
- docs/maestro-cheatsheet.md for a one-page command and runtime quick reference
- docs/cicd.md for CI/CD pipeline workflows, release process, and Mermaid diagrams
- docs/runtime-antigravity.md for Antigravity runtime specifics
- docs/runtime-claude.md for Claude runtime specifics
- docs/runtime-codex.md for Codex runtime specifics
- docs/runtime-qwen.md for Qwen runtime specifics
Canonical source lives under src/. The generator writes the agent stubs, commands, skills, manifests, hook registrations, policy pack, and detached src/ payloads under agents/, commands/, policies/, antigravity/, claude/, plugins/maestro/, and qwen/; update src/ first, then regenerate. A few runtime files are maintained by hand, mainly the thin MCP-server and hook-runner shims, the READMEs, and QWEN.md (CONTRIBUTING.md lists them).
npm ci
node scripts/generate.js
git diff --exit-code --name-only
npm test
npm run pack:verify
npm run release:artifacts
npm run release:verify-artifactsRelease validation creates dist/release/maestro-vX.Y.Z-extension.tar.gz. The archive is intentionally generic: it unpacks with qwen-extension.json, .claude-plugin/marketplace.json, and .agents/plugins/marketplace.json at the root, plus the runtime payloads needed by Antigravity (antigravity/), Claude Code, Codex, and Qwen Code.
Stable releases publish three aligned outputs:
- Git tag
vX.Y.Z - npm package
@josstei/[email protected] - GitHub Release asset
maestro-vX.Y.Z-extension.tar.gz
Codex plugin releases launch the MCP server through the matching npm package version. The Antigravity plugin is self-contained: an installed copy runs the MCP server and hooks from its bundled antigravity/src/. Hook installation is explicit via npm run install-hooks; package, pack, and publish flows do not install git hooks.
Apache-2.0