Multi-agent orchestration extension for Gemini CLI. Maestro assembles specialized development teams and coordinates them through structured design, planning, and execution workflows — plus standalone commands for code review, debugging, security auditing, and performance analysis.
Maestro transforms Gemini CLI into a true multi-agent orchestration platform. Instead of a single AI session handling everything, Maestro delegates work to 12 specialized subagents — each with its own context, tools, and expertise — coordinated by a TechLead orchestrator. Beyond full orchestration workflows, Maestro provides standalone commands for common engineering tasks that can be run independently.
- Guided Design Dialogue: Structured requirements gathering with multiple-choice questions and architectural approach proposals
- Automated Planning: Generates implementation plans with phase dependencies, agent assignments, and parallelization opportunities
- Parallel Execution: Independent phases run concurrently through parallel subagent invocation
- Session Persistence: All orchestration state tracked in YAML+Markdown files for reliable resumption
- Least-Privilege Security: Each subagent receives only the tools required for its role
- Standalone Commands: Direct access to code review, debugging, security audit, and performance analysis without full orchestration
Maestro relies on Gemini CLI's experimental subagent system. You must enable it in your Gemini CLI settings.json:
{
"experimental": {
"enableAgents": true
}
}Warning: Subagents are experimental and operate in YOLO mode — they execute tools (shell commands, file writes) without individual confirmation for each step. Review the subagents documentation for details.
The settings.json file is located at:
- macOS/Linux:
~/.gemini/settings.json - Windows:
%USERPROFILE%\.gemini\settings.json
gemini extensions install https://github.com/josstei/maestro-geminigit clone https://github.com/josstei/maestro-gemini
cd maestro-gemini
gemini extensions link maestro/After installation, restart Gemini CLI for the extension to load.
/maestro.orchestrate Build a REST API for a task management system with user authentication
Maestro will:
- Engage you in a structured design dialogue
- Present 2-3 architectural approaches with trade-offs
- Generate a design document for your approval
- Create a detailed implementation plan with agent assignments
- Execute the plan phase by phase, delegating to specialized agents
- Track all progress in session state files
/maestro.resume
Maestro reads the session state, presents a status summary, and continues from where it left off.
/maestro.review
Automatically detects staged changes or last commit diff and runs a structured code review.
Initiates the full Maestro orchestration workflow.
Usage: /maestro.orchestrate <task description>
Behavior:
- Checks for existing active sessions in
.gemini/state/ - If an active session exists, offers to resume or archive it
- Begins the four-phase orchestration workflow:
- Phase 1: Design Dialogue
- Phase 2: Team Assembly & Planning
- Phase 3: Execution
- Phase 4: Completion & Archival
Resumes an interrupted orchestration session.
Usage: /maestro.resume
Behavior:
- Reads
.gemini/state/active-session.mddirectly via file injection - Parses session metadata and phase statuses
- Presents a status summary with completed/pending/failed phases
- If errors exist from the previous run, presents them and asks for guidance
- Continues execution from the last active phase using the execution and delegation skills
Executes an existing implementation plan, skipping design and planning phases.
Usage: /maestro.execute <path-to-implementation-plan>
Behavior:
- Reads the specified implementation plan file
- Creates a session state file for tracking
- Presents an execution summary for user confirmation
- Executes phases according to the plan with full progress tracking
- Archives the session on completion
Runs a standalone code review on staged changes, last commit, or specified paths.
Usage: /maestro.review [file paths or glob patterns]
Behavior:
- Auto-detects review scope: user-specified paths > staged changes > last commit diff
- Confirms detected scope with the user
- Delegates to the code-reviewer agent
- Presents findings classified by severity (Critical, Major, Minor, Suggestion)
- Every finding references a specific file and line number
Focused debugging session to investigate and diagnose an issue.
Usage: /maestro.debug <issue description>
Behavior:
- Delegates to the debugger agent with the issue description
- Follows systematic methodology: reproduce, hypothesize, investigate, isolate, verify
- Presents root cause analysis with evidence, execution trace, and recommended fix
Runs a security assessment on the specified scope.
Usage: /maestro.security-audit <scope>
Behavior:
- Delegates to the security-engineer agent
- Reviews for OWASP Top 10 vulnerabilities, traces data flow, audits authentication/authorization
- Presents findings with CVSS-aligned severity, proof of concept, and remediation steps
Runs a performance analysis on the specified scope.
Usage: /maestro.perf-check <scope>
Behavior:
- Delegates to the performance-engineer agent
- Establishes baseline, profiles hotspots, analyzes bottlenecks
- Presents optimization recommendations ranked by impact-to-effort ratio
Displays the current orchestration session status.
Usage: /maestro.status
Behavior:
- Reads the active session state via file injection
- Presents phase-by-phase status, file manifest, token usage, and errors
- Read-only — does not modify state or continue execution
Archives the current active orchestration session.
Usage: /maestro.archive
Behavior:
- Checks for an active session
- Presents a summary and asks for confirmation
- Moves design document, implementation plan, and session state to archive directories
- Verifies archival was successful
Maestro uses skills to encapsulate detailed methodologies that are activated on demand, keeping the base context lean.
| Skill | Purpose | Activated By |
|---|---|---|
design-dialogue |
Structured requirements gathering and architectural design convergence | /maestro.orchestrate (Phase 1) |
implementation-planning |
Phase decomposition, agent assignment, and plan generation | /maestro.orchestrate (Phase 2) |
execution |
Phase execution protocols, error handling, and completion workflows | /maestro.orchestrate (Phase 3), /maestro.execute, /maestro.resume |
delegation |
Subagent prompt construction, scope boundaries, and parallel delegation | Any phase involving subagent delegation |
session-management |
Session creation, state updates, resume protocol, and archival | /maestro.orchestrate, /maestro.resume, /maestro.archive, /maestro.status |
code-review |
Scope detection, severity classification, and structured review output | /maestro.review |
validation |
Build/lint/test pipeline, project type detection, and result interpretation | Post-phase validation during execution |
Maestro coordinates 12 specialized subagents:
| Agent | Specialization | Tools | Model |
|---|---|---|---|
| architect | System design, technology selection, component design | read, glob, search, web search | Pro |
| api-designer | REST/GraphQL endpoint design, API contracts | read, glob, search | Pro |
| coder | Feature implementation, clean code, SOLID principles | read, glob, search, write, replace, shell | Pro |
| code-reviewer | Code quality review, best practices, security | read, glob, search | Pro |
| data-engineer | Schema design, query optimization, ETL pipelines | read, glob, search, write, replace, shell | Pro |
| debugger | Root cause analysis, log analysis, execution tracing | read, glob, search, shell | Pro |
| devops-engineer | CI/CD pipelines, containerization, infrastructure | read, glob, search, write, replace, shell | Pro |
| performance-engineer | Profiling, bottleneck identification, optimization | read, glob, search, shell | Pro |
| refactor | Code modernization, technical debt, design patterns | read, glob, search, write, replace | Pro |
| security-engineer | Vulnerability assessment, OWASP, threat modeling | read, glob, search, shell | Pro |
| tester | Unit/integration/E2E tests, TDD, coverage analysis | read, glob, search, write, replace, shell | Pro |
| technical-writer | API docs, READMEs, architecture documentation | read, glob, search, write, replace | Flash |
- Read-only agents (architect, api-designer, code-reviewer): Produce analysis and recommendations
- Read + Shell agents (debugger, performance-engineer, security-engineer): Investigate without modifying files
- Read + Write agents (refactor, technical-writer): Modify code/docs without shell access
- Full access agents (coder, data-engineer, devops-engineer, tester): Complete implementation capabilities
Maestro creates the following directories in your project:
<your-project>/
└── .gemini/
├── plans/ # Active design docs and implementation plans
│ ├── archive/ # Completed plans
│ ├── YYYY-MM-DD-<topic>-design.md
│ └── YYYY-MM-DD-<topic>-impl-plan.md
└── state/ # Session tracking
├── archive/ # Completed sessions
└── active-session.md # Current orchestration state
Maestro tracks orchestration progress in .gemini/state/active-session.md with:
- Phase status tracking: pending, in_progress, completed, failed, skipped
- File manifest: Files created, modified, and deleted per phase
- Error tracking: Per-phase error logs with retry counts and resolution records
- Token usage: Per-agent, per-phase token consumption metrics
All state files use YAML frontmatter for machine-readable metadata and Markdown body for human-readable logs.
The TechLead engages you in a structured conversation to understand requirements:
- Asks one question at a time, preferring multiple-choice format
- Covers problem scope, constraints, technology preferences, quality requirements, and deployment context
- Presents 2-3 architectural approaches with pros, cons, and recommendations
- Builds the design document section by section, validating each with you
After design approval, the TechLead:
- Analyzes the design for components, interfaces, and dependencies
- Assigns phases to specialized agents based on task domain
- Identifies parallel execution opportunities
- Generates a detailed implementation plan for your approval
With plan approval, the TechLead:
- Delegates work to subagents phase by phase
- Runs parallel phases concurrently when dependencies allow
- Updates session state after each phase completion
- Handles errors with up to 2 automatic retries before escalating
After all phases complete:
- Final review of all deliverables
- Session state marked as completed
- Plans and state files archived to
archive/subdirectories - Summary delivered with files changed, token usage, and next steps
- Verify the extension is linked:
gemini extensions list - Restart Gemini CLI after installation or linking
- Check
gemini-extension.jsonexists in the maestro directory
- Ensure GEMINI.md is present in the maestro directory
- Check that
commands/maestro.orchestrate.tomlexists - Restart Gemini CLI
- Verify
.gemini/state/active-session.mdexists in your project - Check the YAML frontmatter is valid (no syntax errors)
- If corrupted, manually fix the YAML or delete and start fresh with
/maestro.orchestrate
- Maestro automatically retries failed phases up to 2 times
- If retries are exhausted, you'll be asked for guidance
- Check the session state file for detailed error logs
- Common causes: file conflicts, missing dependencies, validation failures
- Primary model:
gemini-3-pro-previewfor all agents requiring strong reasoning - Cost-optimized:
gemini-3-flash-previewfor the technical-writer agent - Fallback: When Gemini 3 models are unavailable, agents fall back to
gemini-2.5-pro
MIT