Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/josstei-maestro-orchestrate/badge.svg)](/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

i

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.

  1. {
  2. "name": "maestro-orchestrator",
  3. "owner": {
  4. "name": "josstei"
  5. },
  6. "metadata": {
  7. "description": "Maestro multi-agent orchestration platform for Claude Code",
  8. "version": "1.6.4"
  9. },
  10. "plugins": [
  11. {
  12. "name": "maestro",
  13. "source": "./claude",
  14. "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",
  15. "version": "1.6.4",
  16. "author": {
  17. "name": "josstei",
  18. "email": "hello@josstei.dev",
  19. "url": "https://github.com/josstei"
  20. },
  21. "homepage": "https://github.com/josstei/maestro-orchestrate",
  22. "repository": "https://github.com/josstei/maestro-orchestrate",
  23. "license": "Apache-2.0",
  24. "keywords": [
  25. "orchestration",
  26. "multi-agent",
  27. "planning",
  28. "execution",
  29. "agents"
  30. ],
  31. "category": "productivity"
  32. }
  33. ]
  34. }
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.

  1. # Maestro
  2. [![Version](https://img.shields.io/badge/version-1.6.4-blue)](https://github.com/josstei/maestro-orchestrate/releases)
  3. [![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
  4. [![Antigravity](https://img.shields.io/badge/Antigravity-plugin-orange)](docs/runtime-antigravity.md)
  5. [![Claude Code](https://img.shields.io/badge/Claude_Code-plugin-blue)](https://docs.anthropic.com/en/docs/claude-code)
  6. [![Codex](https://img.shields.io/badge/Codex-plugin-black)](docs/runtime-codex.md)
  7. [![Qwen Code](https://img.shields.io/badge/Qwen_Code-extension-purple)](https://github.com/QwenLM/qwen-code)
  8. 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**.
  9. ## Runtime Targets
  10. | Runtime | Location | Public Surface | Notes |
  11. |---------|----------|----------------|-------|
  12. | Antigravity | `antigravity/` | `/maestro:*` | Plugin skills, kebab-case subagents run with `invoke_subagent`, SessionStart and `run_command` policy hooks |
  13. | Claude Code | `claude/` | `/orchestrate`, `/review-code`, ... | Kebab-case agents with `maestro:` subagent names |
  14. | Codex | `plugins/maestro/` | `$maestro:*` | Plugin skills, `spawn_agent`, no runtime hooks |
  15. | Qwen Code | repo root + `qwen/hooks.json` | `/maestro:*` | Snake-case agents, TOML commands, `QWEN.md` context file, `SubagentStart`/`SubagentStop` hooks |
  16. ## Getting Started
  17. ### Prerequisites
  18. - One supported runtime: Antigravity (the `agy` CLI or the Antigravity app), Claude Code, Codex, or Qwen Code
  19. - Node.js 20+ for the MCP server and helper scripts
  20. ### Installation
  21. #### Antigravity
  22. ```bash
  23. agy plugin install https://github.com/josstei/maestro-orchestrate/tree/main/antigravity
  24. ```
  25. Restart `agy` afterwards: Antigravity discovers a newly installed plugin only on startup. Verify with `agy plugin list`.
  26. Local development (link the plugin directory, then restart `agy`; a linked plugin loads but is not listed by `agy plugin list`):
  27. ```bash
  28. git clone https://github.com/josstei/maestro-orchestrate
  29. mkdir -p ~/.gemini/config/plugins
  30. ln -s "$PWD/maestro-orchestrate/antigravity" ~/.gemini/config/plugins/maestro
  31. ```
  32. More Antigravity-specific setup and runtime details live in [antigravity/README.md](antigravity/README.md) and [docs/runtime-antigravity.md](docs/runtime-antigravity.md).
  33. #### Claude Code
  34. Marketplace install:
  35. ```bash
  36. claude plugin marketplace add josstei/maestro-orchestrate
  37. claude plugin install maestro@maestro-orchestrator --scope user
  38. ```
  39. Development / temporary loading:
  40. ```bash
  41. git clone https://github.com/josstei/maestro-orchestrate
  42. claude --plugin-dir /path/to/maestro-orchestrate/claude
  43. ```
  44. More Claude-specific setup and plugin management lives in [claude/README.md](claude/README.md).
  45. #### Codex
  46. Register the marketplace:
  47. ```bash
  48. codex plugin marketplace add josstei/maestro-orchestrate
  49. ```
  50. Then start Codex, run `/plugins` to browse, select **Maestro**, and choose **Install**.
  51. Local development (path must start with `./`, `../`, `/`, or `~/` — Codex otherwise treats bare `owner/repo` as a GitHub source):
  52. ```bash
  53. git clone https://github.com/josstei/maestro-orchestrate
  54. codex plugin marketplace add /absolute/path/to/maestro-orchestrate
  55. # then: start Codex, run `/plugins`, select Maestro → Install
  56. ```
  57. 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).
  58. #### Qwen Code
  59. ```bash
  60. qwen extensions install https://github.com/josstei/maestro-orchestrate
  61. ```
  62. Local development:
  63. ```bash
  64. git clone https://github.com/josstei/maestro-orchestrate
  65. cd maestro-orchestrate
  66. qwen extensions link .
  67. ```
  68. Verify with `qwen extensions list`. Qwen Code reads `QWEN.md` as its context file and loads the `/maestro:*` commands from `commands/maestro/*.toml`.
  69. ### Quick Start
  70. Start a full orchestration with the runtime-specific entrypoint:
  71. | Runtime | Example |
  72. |---------|---------|
  73. | Antigravity | `/maestro:orchestrate Build a REST API for a task management system with user authentication` |
  74. | Claude Code | `/orchestrate Build a REST API for a task management system with user authentication` |
  75. | Codex | `$maestro:orchestrate Build a REST API for a task management system with user authentication` |
  76. | Qwen Code | `/maestro:orchestrate Build a REST API for a task management system with user authentication` |
  77. 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/`.
  78. ## Examples
  79. Usage examples: [EXAMPLES.md](EXAMPLES.md). Qwen Code forms shown:
  80. - Full orchestration: `/maestro:orchestrate Build a REST API for a task management system with user authentication`
  81. - Standalone review: `/maestro:review Review the staged changes for correctness, regressions, security, maintainability risk, and missing tests`
  82. - Security audit: `/maestro:security-audit Audit authentication, authorization, data exposure, secret handling, and exploitability risks`
  83. ## Configuration
  84. Defaults work; these settings tune behavior:
  85. | Setting | Default | Purpose |
  86. |---------|---------|---------|
  87. | `MAESTRO_STATE_DIR` | `docs/maestro` | Session, plan, and archive output path |
  88. | `MAESTRO_EXECUTION_MODE` | `ask` | Choose `parallel`, `sequential`, or prompt |
  89. | `MAESTRO_VALIDATION_STRICTNESS` | `normal` | Post-phase validation strictness (`strict`, `normal`, or `lenient`) |
  90. | `MAESTRO_AUTO_ARCHIVE` | `true` | Archive successful sessions automatically |
  91. | `MAESTRO_MAX_RETRIES` | `2` | Retry limit for failed phases |
  92. | `MAESTRO_MAX_CONCURRENT` | `0` | Parallel-agent cap, where `0` means no Maestro cap |
  93. | `MAESTRO_DISABLED_AGENTS` | unset | Specialists to exclude from assignment |
  94. ## Commands
  95. | Capability | Antigravity | Claude Code | Codex | Qwen Code |
  96. |------------|-------------|-------------|-------|-----------|
  97. | Orchestrate | `/maestro:orchestrate` | `/orchestrate` | `$maestro:orchestrate` | `/maestro:orchestrate` |
  98. | Execute | `/maestro:execute` | `/execute` | `$maestro:execute` | `/maestro:execute` |
  99. | Resume | `/maestro:resume-session` | `/resume-session` | `$maestro:resume-session` | `/maestro:resume` |
  100. | Status | `/maestro:status` | `/status` | `$maestro:status` | `/maestro:status` |
  101. | Archive | `/maestro:archive` | `/archive` | `$maestro:archive` | `/maestro:archive` |
  102. | Review | `/maestro:review-code` | `/review-code` | `$maestro:review-code` | `/maestro:review` |
  103. | Debug | `/maestro:debug-workflow` | `/debug-workflow` | `$maestro:debug-workflow` | `/maestro:debug` |
  104. | Security Audit | `/maestro:security-audit` | `/security-audit` | `$maestro:security-audit` | `/maestro:security-audit` |
  105. | Performance Check | `/maestro:perf-check` | `/perf-check` | `$maestro:perf-check` | `/maestro:perf-check` |
  106. | SEO Audit | `/maestro:seo-audit` | `/seo-audit` | `$maestro:seo-audit` | `/maestro:seo-audit` |
  107. | Accessibility Audit | `/maestro:a11y-audit` | `/a11y-audit` | `$maestro:a11y-audit` | `/maestro:a11y-audit` |
  108. | Compliance Check | `/maestro:compliance-check` | `/compliance-check` | `$maestro:compliance-check` | `/maestro:compliance-check` |
  109. 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.
  110. 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`.
  111. Qwen Code does not remap any entry point; it keeps `/maestro:review`, `/maestro:debug`, and `/maestro:resume`.
  112. ## Workflow
  113. - **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.
  114. - **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.
  115. ## Outputs and Success Criteria
  116. 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.
  117. 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.
  118. ## Security and Permissions
  119. 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.
  120. ## Documentation
  121. - [EXAMPLES.md](EXAMPLES.md) for copyable usage scenarios across all runtimes
  122. - [docs/overview.md](docs/overview.md) for the project model and generated structure
  123. - [docs/architecture.md](docs/architecture.md) for orchestration internals and architecture layout
  124. - [docs/usage.md](docs/usage.md) for development workflow, settings, and command surfaces
  125. - [docs/flow.md](docs/flow.md) for the orchestration workflow steps and hard gates
  126. - [docs/maestro-cheatsheet.md](docs/maestro-cheatsheet.md) for a one-page command and runtime quick reference
  127. - [docs/cicd.md](docs/cicd.md) for CI/CD pipeline workflows, release process, and Mermaid diagrams
  128. - [docs/runtime-antigravity.md](docs/runtime-antigravity.md) for Antigravity runtime specifics
  129. - [docs/runtime-claude.md](docs/runtime-claude.md) for Claude runtime specifics
  130. - [docs/runtime-codex.md](docs/runtime-codex.md) for Codex runtime specifics
  131. - [docs/runtime-qwen.md](docs/runtime-qwen.md) for Qwen runtime specifics
  132. ## Development and Release Validation
  133. 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).
  134. ```bash
  135. npm ci
  136. node scripts/generate.js
  137. git diff --exit-code --name-only
  138. npm test
  139. npm run pack:verify
  140. npm run release:artifacts
  141. npm run release:verify-artifacts
  142. ```
  143. 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.
  144. Stable releases publish three aligned outputs:
  145. - Git tag `vX.Y.Z`
  146. - npm package `@josstei/maestro@X.Y.Z`
  147. - GitHub Release asset `maestro-vX.Y.Z-extension.tar.gz`
  148. 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.
  149. ## License
  150. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.