maestro-orchestrator
Multi-agent orchestration platform for Gemini CLI, Claude Code, Codex, and Qwen Code — 39 specialists, parallel subagents, persistent sessions, and built-in code review, debugging, security, SEO, accessibility, and compliance tools
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/josstei-maestro-orchestrate)HTML
<a href="/listings/josstei-maestro-orchestrate"><img src="/api/listings/josstei-maestro-orchestrate/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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](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](plugins/maestro/README.md) and [docs/runtime-codex.md](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/`.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 34 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "name": "maestro-orchestrator",
- "owner": {
- "name": "josstei"
- },
- "metadata": {
- "description": "Maestro multi-agent orchestration platform for Claude Code",
- "version": "1.6.4"
- },
- "plugins": [
- {
- "name": "maestro",
- "source": "./claude",
- "description": "Multi-agent development orchestration platform — 39 specialists, 4-phase orchestration, native parallel subagents, persistent sessions, and standalone review/debug/security/perf/seo/a11y/compliance commands",
- "version": "1.6.4",
- "author": {
- "name": "josstei",
- "email": "hello@josstei.dev",
- "url": "https://github.com/josstei"
- },
- "homepage": "https://github.com/josstei/maestro-orchestrate",
- "repository": "https://github.com/josstei/maestro-orchestrate",
- "license": "Apache-2.0",
- "keywords": [
- "orchestration",
- "multi-agent",
- "planning",
- "execution",
- "agents"
- ],
- "category": "productivity"
- }
- ]
- }
README.md · README · 215 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # Maestro
- [](https://github.com/josstei/maestro-orchestrate/releases)
- [](LICENSE)
- [](docs/runtime-antigravity.md)
- [](https://docs.anthropic.com/en/docs/claude-code)
- [](docs/runtime-codex.md)
- [](https://github.com/QwenLM/qwen-code)
- 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 Targets
- | 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 |
- ## Getting Started
- ### Prerequisites
- - One supported runtime: Antigravity (the `agy` CLI or the Antigravity app), Claude Code, Codex, or Qwen Code
- - Node.js 20+ for the MCP server and helper scripts
- ### Installation
- #### Antigravity
- ```bash
- agy plugin install https://github.com/josstei/maestro-orchestrate/tree/main/antigravity
- ```
- Restart `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`):
- ```bash
- git clone https://github.com/josstei/maestro-orchestrate
- mkdir -p ~/.gemini/config/plugins
- ln -s "$PWD/maestro-orchestrate/antigravity" ~/.gemini/config/plugins/maestro
- ```
- More Antigravity-specific setup and runtime details live in [antigravity/README.md](antigravity/README.md) and [docs/runtime-antigravity.md](docs/runtime-antigravity.md).
- #### Claude Code
- Marketplace install:
- ```bash
- claude plugin marketplace add josstei/maestro-orchestrate
- claude plugin install maestro@maestro-orchestrator --scope user
- ```
- Development / temporary loading:
- ```bash
- 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](claude/README.md).
- #### Codex
- Register the marketplace:
- ```bash
- 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):
- ```bash
- 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](plugins/maestro/README.md) and [docs/runtime-codex.md](docs/runtime-codex.md).
- #### Qwen Code
- ```bash
- qwen extensions install https://github.com/josstei/maestro-orchestrate
- ```
- Local development:
- ```bash
- 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`.
- ### Quick Start
- 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/`.
- ## Examples
- Usage examples: [EXAMPLES.md](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`
- ## 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_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 |
- ## Commands
- | 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`.
- ## Workflow
- - **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.
- ## Outputs and Success Criteria
- 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.
- ## Security and Permissions
- 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.
- ## Documentation
- - [EXAMPLES.md](EXAMPLES.md) for copyable usage scenarios across all runtimes
- - [docs/overview.md](docs/overview.md) for the project model and generated structure
- - [docs/architecture.md](docs/architecture.md) for orchestration internals and architecture layout
- - [docs/usage.md](docs/usage.md) for development workflow, settings, and command surfaces
- - [docs/flow.md](docs/flow.md) for the orchestration workflow steps and hard gates
- - [docs/maestro-cheatsheet.md](docs/maestro-cheatsheet.md) for a one-page command and runtime quick reference
- - [docs/cicd.md](docs/cicd.md) for CI/CD pipeline workflows, release process, and Mermaid diagrams
- - [docs/runtime-antigravity.md](docs/runtime-antigravity.md) for Antigravity runtime specifics
- - [docs/runtime-claude.md](docs/runtime-claude.md) for Claude runtime specifics
- - [docs/runtime-codex.md](docs/runtime-codex.md) for Codex runtime specifics
- - [docs/runtime-qwen.md](docs/runtime-qwen.md) for Qwen runtime specifics
- ## Development and Release Validation
- 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](CONTRIBUTING.md#architecture-canonical-source-and-generated-runtimes) lists them).
- ```bash
- 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-artifacts
- ```
- Release 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/maestro@X.Y.Z`
- - 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.
- ## License
- Apache-2.0
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.