Raw capture — raw/maestro.md

url: https://github.com/SnapdragonPartners/maestro date_fetched: 2026-07-05 backfilled: true

Maestro is a tool that uses AI to write full applications in a disciplined way that reflects good software engineering principles.

In some ways, it's an agent orchestration tool. But unlike most others, Maestro bakes in structure, workflow, and opinions drawn from real-world experience managing large software projects. The goal is production-ready apps, not just code snippets.

The big idea behind Maestro is that since LLMs are trained on and exhibit human behaviors it makes sense to organize them to operate like the most high performing human teams rather than relying on a single model or agent no matter how good.

This project is developed and actively maintained by Snapdragon Partners. Tokens for developing Maestro are expensive but we're keeping the community version of Maestro free. If you like Maestro, any support you can provide via GitHub Sponsors would be appreciated!

Step 1:Install Maestro via Homebrew, APT, or direct download from releases.

Option A: Homebrew (macOS)brew install --cask SnapdragonPartners/tap/maestro

Option B: Control Panel App (macOS)A native macOS app is available as a graphical wrapper for the Maestro CLI. Download it from maestro-macos releases. You can still use Homebrew or the CLI directly if you prefer, but the control panel app contains everything you need to use Maestro.

Option C: APT (Debian/Ubuntu)# Add the Maestro APT repository (one-time setup) curl -fsSL https://snapdragonpartners.github.io/maestro/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/maestro.gpg echo "deb [signed-by=/usr/share/keyrings/maestro.gpg] https://snapdragonpartners.github.io/maestro stable main" | sudo tee /etc/apt/sources.list.d/maestro.list # Install (or upgrade) sudo apt update && sudo apt install maestro

Option D: Direct downloadDownload the binary for your platform from releases and install it somewhere in your path.

Step 2:Provide your API keys for the models you want to use and GitHub. You have two options:

Option A: Environment variables(traditional)export OPENAI_API_KEY=sk-... export ANTHROPIC_API_KEY=sk-ant-... export GOOGLE_GENAI_API_KEY=AIza... # Optional, for Gemini models export GITHUB_TOKEN=ghp-... # Optional: Ollama for local models (default: http://localhost:11434) export OLLAMA_HOST=http://localhost:11434 # Optional: Enable web search for agents (Google Custom Search) export GOOGLE_SEARCH_API_KEY=AIza... export GOOGLE_SEARCH_CX=... # Your Custom Search Engine ID

Tip:If you use Claude Code or other tools that readANTHROPIC_API_KEY, you can setMAESTRO_ANTHROPIC_API_KEYinstead — Maestro checksMAESTRO_-prefixed env vars first, letting you use different keys for Maestro and other tools. This works for all providers:MAESTRO_OPENAI_API_KEY,MAESTRO_GOOGLE_GENAI_API_KEY,MAESTRO_GITHUB_TOKEN.

Option B: Configure via Web UI(easier)Skip this step entirely and just run Maestro. If any required API keys are missing, Maestro will automatically open a setup page in the Web UI where you can paste your keys into a browser form. Keys are encrypted and stored locally.

Step 3:Create a project directory (projectdir) and switch to it.mkdir myproject && cd myproject

Step 4:Run MaestromaestroIf any required API keys are missing, Maestro will launch in

setup mode— open the Web UI (default http://localhost:8080) and follow the prompts to enter your keys. Once all keys are configured, Maestro continues startup automatically.

Important:When Maestro generates a password, it is used for both WebUI login and secrets encryption. Record it somewhere safe — if lost, any secrets stored through the WebUI cannot be recovered. To use your own persistent password, set theMAESTRO_PASSWORDenvironment variable before running Maestro.

Step 5:Open the web UI at http://localhost:8080 (you can change this in the config file.)

Config settings are in /.maestro/config.json.

Much more extensive documentation including configuration settings is available in the Wiki.

Much simpler setup than other frameworks: Maestro uses just a single binary and your existing development tools. It comes with preset config and workflow that work out of the box, but can be customized as needed.

Most frameworks require wrestling with Python versions, dependency hell, or complex setup. With Maestro:

Maestro provides out-of-box support for Anthropic, Google, and OpenAI models through their official SDKs (so it should support the latest models as soon as they become available.) Maestro also supports open source and open weight models runnning locally through Ollama.

You can mix-and-match models by agent type - in fact, that's the recommended configuration since heterogeneous models often catch errors that models from the same provider may not.

All LLM provider I/O goes through maestro-llms — an app-neutral, open-source Go toolkit (one ChatClient contract, one error model, composable retry/circuit/timeout/rate-limit middleware; it also offers embeddings, which Maestro itself doesn't currently use) extracted from Maestro so other projects can reuse it and share maintenance. If you're building something that talks to LLM providers, you can use it directly without Maestro.

- Transforms requirements into

Coders(many):- Pull stories from a queue - Develop plans, then code - Must check in periodically - Run automated tests before completing work - Submit PRs for architect review

Coders are goroutines that fully terminate and restart between stories. All state (stories, messages, progress, tokens, costs, etc.) is persisted in a SQLite database.

If a coder stalls or fails, Maestro automatically retries or reassigns. Questions can bubble up to a human via CLI or web UI.

See the canonical state diagrams for details:

Maestro distinguishes three story types:

This distinction is transparent to the user—architect generates stories automatically.

Maestro operates in several distinct modes depending on project state and user intent:

Mode When It Runs What It Does
Bootstrap Automatically on new projects Sets up basic project infrastructure
Development Default operating mode Main workflow for building features
Airplane --airplaneflag Fully offline with local Gitea + Ollama
Claude Code coder_mode: "claude-code" Uses Claude Code for implementation
Demo User-triggered via WebUI Runs the application for testing
Run --runflag Runs app + dependencies only (no agents)
Hotfix User requests urgent fix Fast path for production issues
Maintenance After N specs complete Cleans up technical debt
Discovery Future Onboards existing codebases

See docs/MODES.md for detailed documentation on each mode.

Run mode starts your application with its dependencies without the full orchestrator:

maestro --runThis is useful for:

Run mode starts compose services (if configured), builds and runs the app, and cleans up on shutdown.

Airplane mode enables fully offline multi-agent development without GitHub or external LLM APIs:

# Start in airplane mode
maestro --airplane
# After returning online, sync changes to GitHub
maestro --sync

Requirements:

How it works:

Configuration:

{
  "default_mode": "airplane",
  "agents": {
    "airplane": {
      "coder_model": "ollama:qwen2.5-coder:14b",
      "architect_model": "ollama:mistral-nemo:latest"
    }
  }
}

See docs/AIRPLANE_MODE.md for detailed specification.

Maestro tracks and displays:

Maestro includes a knowledge graph system that captures architectural patterns, design decisions, and coding conventions. This graph serves as "institutional memory" that helps agents maintain consistency across stories.

The knowledge graph is stored in .maestro/knowledge.dot in your repository and automatically provides relevant context to coders during planning. When a coder starts a story, Maestro extracts key terms and builds a focused "knowledge pack" with 20-30 related patterns. The architect reviews whether implementations follow these patterns and validates any updates to the graph.

Benefits:

See docs/wiki/DOCS_WIKI.md for user-friendly overview or docs/DOC_GRAPH.md for technical specification.

Agents can optionally search the web to find current documentation, API references, and library versions. This is useful when agents need information beyond their training data cutoff.

To enable web search:

When both variables are set, web search is automatically enabled for all agents. If unset, agents will log a warning and continue without search capability.

You can also control search explicitly in .maestro/config.json:

{
  "search": {
    "enabled": true  // or false to disable even if keys are present
  }
}

Hotfix mode provides a fast path for urgent, small changes that bypass the normal spec-driven development queue. This mimics the "live team / dev team" pattern common in engineering organizations, where a dedicated rotation handles production issues while the main team continues feature development.

When you need a quick fix without waiting for in-progress feature work to complete:

Examples of hotfix requests:

The architect validates hotfix requests to ensure they don't have dependencies on in-progress work, then dispatches them immediately.

See docs/HOTFIX_MODE_SPEC.md for detailed specification.

Maestro includes an automated maintenance system that manages technical debt between specs. After a configurable number of specs complete, maintenance mode triggers automatically and performs:

Programmatic Tasks (no LLM required):

LLM-Driven Stories (run as express stories):

Maintenance runs autonomously and produces a summary report posted to chat. All maintenance PRs auto-merge after CI passes.

Configuration in .maestro/config.json:

{
  "maintenance": {
    "enabled": true,
    "after_specs": 1,
    "stories": {
      "knowledge_sync": true,
      "doc_verify": true,
      "todo_scan": true
    }
  }
}

See docs/MAINTENANCE_MODE_SPEC.md for detailed specification.

Maestro supports an alternative coder implementation that uses Claude Code as a subprocess instead of direct LLM API calls. This mode leverages Claude Code's built-in tooling (file operations, bash execution, etc.) while Maestro handles orchestration and signal detection.

How it works:

Configuration:

{
  "agents": {
    "coder_mode": "claude-code"
  }
}

Benefits:

Claude Code is auto-installed in the container on first run.

Q: How do I start a new project? Open the web UI at http://localhost:8080 and start a PM interview (you can override this port in the config file.) The PM will ask questions about your requirements, read your existing codebase if applicable, and generate a specification. The architect will then review it and create stories for coders to implement.

Q: Can I provide my own specification instead of using the PM? Yes. You can place a markdown specification file in your project directory and the architect will parse it directly, skipping the PM interview.

Q: Do I have to use GitHub? In standard mode, yes—Maestro's workflow relies on PRs and merges. However, airplane mode (--airplane) replaces GitHub with a local Gitea server for fully offline development. When you're back online, use --sync to push changes to GitHub.

Q: Can I skip Docker? No. Coders always run in Docker containers for isolation and reproducibility.

Q: Why doesn't the architect write code? By design. The architect enforces engineering discipline, ensures coders don't review their own work, and keeps technical debt low.

Q: Is this secure? Maestro is intended as a single-user tool running locally. All agents run in Docker containers as a non-privileged user (1000:1000) with security hardening including read-only root filesystem, no-new-privileges, and resource limits. Combined with Docker isolation, this provides reasonable security for local development, certainly as good or significantly better than other agent-based development systems.

Q: What happens if Maestro crashes? All stories, states, tool use, messages, and progress are persisted in SQLite. On restart, coders and architect resume where they left off.

MIT