Multi-agent orchestration platform for Gemini CLI and Claude Code — 22 specialists, parallel subagents, persistent sessions, and built-in code review, debugging, security, SEO, accessibility, and compliance tools
AI Agentsagenticai-agentsai-codingai-toolinganthropic
Installation
# Add to your Claude Code skills
git clone https://github.com/josstei/maestro-orchestrate
README.md
Maestro
Multi-agent development orchestration platform — 22 specialists, 4-phase orchestration, native parallel subagents, persistent sessions, and standalone review/debug/security/perf/seo/a11y/compliance commands. Runs on both Gemini CLI and Claude Code.
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Maestro is a multi-agent orchestration platform for Gemini CLI and Claude Code. Instead of a single AI session handling everything, Maestro delegates work to 22 specialized subagents -- each with its own context, tools, and expertise -- coordinated by a TechLead orchestrator. For simple tasks, Maestro uses an Express workflow that collapses design and planning into a single brief before executing. For medium and complex tasks, Maestro follows a structured 4-phase Standard workflow: Design, Plan, Execute, Complete.
The same orchestration engine, agents, and quality gates run on both platforms. Gemini CLI uses the extension at the repo root; Claude Code uses the plugin in the claude/ subdirectory.
Maestro classifies every task by complexity before choosing a workflow. Simple tasks (single concern, few files) get the Express path. Medium tasks (multi-component, clear boundaries) and complex tasks (cross-cutting, multi-service) enter the Standard path with full design dialogue, implementation planning, and phased execution across 22 agents spanning 8 editorial domains.
Features
Express Workflow -- Simple tasks skip ceremony: 1-2 clarifying questions, a structured brief, single-agent delegation, code review, and archival. No design document or implementation plan is created.
Guided Design Dialogue -- Standard workflow includes structured requirements gathering with multiple-choice questions, depth-selectable reasoning (Quick, Standard, Deep), and architectural approach proposals with trade-offs.
Native Parallel Execution -- Independent phases run concurrently through the active runtime's native subagent scheduler, batching phases at the same dependency depth with non-overlapping file ownership.
Session Persistence -- All orchestration state is tracked in YAML+Markdown files with machine-readable frontmatter and human-readable logs, enabling reliable resumption after interruptions.
Hooks-Based Lifecycle Middleware -- Lifecycle hooks for active-agent tracking, session context injection, and handoff validation.
Least-Privilege Security -- Each subagent receives only the tools required for its role through a 4-tier access model enforced via agent frontmatter declarations.
Standalone Commands -- Direct access to code review, debugging, security audit, performance analysis, SEO audit, accessibility audit, and compliance check without full orchestration.
8-Domain Coverage -- Agents span Engineering, Product, Design, Content, SEO, Compliance, Internationalization, and Analytics domains, selected proportionally to task complexity.
MCP-First State Management -- Session state operations use MCP tools for structured I/O and atomic transitions, with filesystem fallback when MCP is unavailable.
Codebase Investigation -- Built-in codebase investigator grounds designs and plans in the actual repository structure, conventions, and integration points before proposing approaches.
Getting Started
Prerequisites
Gemini CLI requires the experimental subagent system. Claude Code users can skip to Installation — subagents are available by default.
Enable subagents in your Gemini CLI settings:
{
"experimental": {
"enableAgents": true
}
}
Warning: Native parallel subagents currently run in autonomous mode. Sequential delegation uses your current Gemini CLI approval mode. Review the subagents documentation for details.
The settings.json file is located at:
macOS/Linux: ~/.gemini/settings.json
Windows: %USERPROFILE%\.gemini\settings.json
Maestro does not auto-edit ~/.gemini/settings.json. Enable experimental.enableAgents manually before running orchestration commands.
git clone https://github.com/josstei/maestro-orchestrate
cd maestro-orchestrate
gemini extensions link .
Verify: gemini extensions list should show maestro.
Claude Code
From Marketplace (recommended):
claude plugin marketplace add josstei/maestro-orchestrate
claude plugin install maestro@maestro-orchestrator --scope user
Development / Testing:
git clone https://github.com/josstei/maestro-orchestrate
claude --plugin-dir /path/to/maestro-orchestrate/claude
Marketplace install is the persistent end-user path. The --plugin-dir flag loads the plugin for a single session and is intended for local development or temporary testing. The Claude Code plugin lives in the claude/ subdirectory (not the repo root).
For installation scopes and plugin management commands, see claude/README.md.
Verify: agents appear with maestro: prefix (e.g., maestro:coder), and /orchestrate, /review, etc. appear in slash-command autocomplete.
Command Names By Runtime
Gemini CLI exposes Maestro as /maestro:* commands. Claude Code exposes the same public entrypoints as top-level slash commands without the maestro: prefix.
Start a full orchestration by describing what you want to build:
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
Maestro will walk you through the complete lifecycle:
Design Dialogue -- Maestro asks structured questions one at a time (problem scope, constraints, technology preferences, quality requirements, deployment context) and presents 2-3 architectural approaches with trade-offs.
Design Review -- The design document is presented section by section for your approval. Each section is 200-300 words covering requirements, architecture, component specs, team composition, risk assessment, and success criteria.
Implementation Planning -- Maestro generates a detailed plan with phase breakdown, agent assignments, dependency graph, parallel execution opportunities, and validation criteria. You review and approve before execution begins.
Execution Mode Selection -- Choose parallel dispatch (independent phases run concurrently as native subagents) or sequential delegation (one phase at a time with intervention opportunities).
Phase-by-Phase Execution -- Specialized agents implement the plan. Session state is updated after each phase with files changed, validation results, and token usage.
Quality Gate -- A final code review blocks completion on unresolved Critical or Major findings. The orchestrator remediates and re-validates until resolved.
Completion & Archival -- Maestro delivers a summary of files changed, token usage by agent, deviations from plan, and recommended next steps. The session is archived automatically.
Express mode example -- For straightforward tasks, Maestro detects low complexity and uses the Express workflow:
Gemini CLI: /maestro:orchestrate Add a health check endpoint to the Express server
Claude Code: /orchestrate Add a health check endpoint to the Express server
Express mode asks 1-2 clarifying questions, presents a structured brief for approval, delegates to a single agent, runs a code review gate, and archives -- all without a full design document or implementation plan.
