{"id":50108766,"url":"https://github.com/kmeng/maestro","last_synced_at":"2026-05-23T12:02:52.413Z","repository":{"id":356359087,"uuid":"1231494802","full_name":"kmeng/maestro","owner":"kmeng","description":"Orchestrate a heterogeneous AI software team. Pay junior prices for senior-level output.","archived":false,"fork":false,"pushed_at":"2026-05-23T06:39:38.000Z","size":1091,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T07:29:17.620Z","etag":null,"topics":["ai-agents","claude-code","cost-optimization","deepseek","llm-orchestration","mcp","multi-agent"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kmeng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":"docs/governance.md","roadmap":"docs/roadmap-v1.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T02:37:05.000Z","updated_at":"2026-05-23T05:55:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kmeng/maestro","commit_stats":null,"previous_names":["kmeng/maestro"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/kmeng/maestro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kmeng%2Fmaestro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kmeng%2Fmaestro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kmeng%2Fmaestro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kmeng%2Fmaestro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kmeng","download_url":"https://codeload.github.com/kmeng/maestro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kmeng%2Fmaestro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33394672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","cost-optimization","deepseek","llm-orchestration","mcp","multi-agent"],"created_at":"2026-05-23T12:02:46.527Z","updated_at":"2026-05-23T12:02:52.406Z","avatar_url":"https://github.com/kmeng.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"maestro/webui/static/maestro-mark.svg\" width=\"120\" alt=\"Maestro\"\u003e\n\n# Maestro\n\n**You conduct. The AI plays.** · Pay junior prices for senior-level output.\n\n[![Release](https://img.shields.io/github/v/release/kmeng/maestro)](https://github.com/kmeng/maestro/releases)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)\n[![Built with Claude Code](https://img.shields.io/badge/built%20with-Claude%20Code-d97757.svg)](https://claude.com/claude-code)\n[![Self-built by AI](https://img.shields.io/badge/self--built%20by-AI-7c3aed.svg)](BUILD_LOG.md)\n\n**English** | [中文](README.zh-CN.md)\n\u003c/div\u003e\n\n\u003e Orchestrate a heterogeneous AI software team. Pay junior prices for senior-level output.\n\nMaestro is an open-source framework that turns Claude Code into the conductor of a complete AI software development team. Instead of burning top-tier model tokens on every task, Maestro routes work to the right specialist at the right cost — Opus for architecture; cheap models (DeepSeek v4-pro / v4-flash today, more providers pluggable) for implementation, document extraction, code review, and commit drafting.\n\nThe result: software development at roughly **10–20% the cost** of a pure flagship-model workflow, with quality gates that catch when the cheap models get it wrong.\n\n\u003e See [docs/savings.md](docs/savings.md) for the measured cost evidence backing this claim.\n\n---\n\n## Why Maestro\n\nA real software team isn't ten senior architects. It's a few seniors directing a larger group of mid-level and junior engineers, each doing what they do best. AI coding tools today don't reflect this — they either burn flagship model tokens on every keystroke, or they downgrade everything to a cheaper model and lose quality.\n\nMaestro takes the obvious next step: **heterogeneous models, role-matched, cost-aware**.\n\n| | Pure Opus | Pure DeepSeek | **Maestro** |\n|---|---|---|---|\n| Cost | 💰💰💰💰💰 | 💰 | 💰💰 |\n| Architecture quality | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ |\n| Boilerplate output | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |\n| Cross-file reasoning | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ |\n| You stay in control | ✅ | ⚠️ | ✅ |\n\n---\n\n## How it works\n\nMaestro runs as an MCP server registered with Claude Code. Your Claude Code session — running on your Pro/Max subscription — becomes the **Maestro (conductor)**, an Opus-powered orchestrator that decomposes work and dispatches it to the rest of the team via MCP tools.\n\n```\n┌──────────────────────────────────────────────────┐\n│  Claude Code (Opus, your subscription)           │\n│  ↳ Maestro: understands intent, plans, reviews   │\n└──────────────────────────────────────────────────┘\n                       ↓ MCP\n┌──────────────────────────────────────────────────┐\n│  Maestro Server (local Python process)           │\n│  ↳ Routes tasks to the right team member         │\n│  ↳ Runs quality gates                            │\n│  ↳ Logs every decision for transparency          │\n└──────────────────────────────────────────────────┘\n        ↓             ↓             ↓             ↓\n┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n│ Coder       │ │ Librarian   │ │ Reviewer    │ │ Scribe      │\n│             │ │             │ │             │ │             │\n│ DeepSeek    │ │ DeepSeek    │ │ DeepSeek    │ │ DeepSeek    │\n│ v4-pro      │ │ v4-flash    │ │ v4-pro      │ │ v4-flash    │\n│             │ │             │ │             │ │             │\n│ Implements  │ │ Extracts    │ │ Reviews     │ │ Drafts      │\n│ from a      │ │ task-       │ │ code        │ │ commits     │\n│ precise     │ │ relevant    │ │ against     │ │ and PR      │\n│ spec        │ │ context     │ │ a spec      │ │ bodies      │\n└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘\n```\n\nThe conductor never disappears — every dispatch and every result flows back through Opus, which integrates the work and makes the next decision. You see everything in your normal Claude Code session.\n\n---\n\n## The team\n\nEach role exists because it does something the others can't do as well — or as cheaply.\n\n### 🏛️ Architect (Opus, the conductor itself)\n\nThis is your Claude Code main session. Owns architectural decisions, cross-cutting concerns, and final integration. The Architect doesn't write boilerplate — it decides what should exist and reviews what comes back.\n\n**Always on**. This is your interface.\n\n### ⚙️ Coder (DeepSeek v4-pro)\n\nImplements code from a precise specification. Tests, validators, CRUD endpoints, data classes, scaffolds, focused refactors. Fast and surprisingly competent when given a clear spec; the Architect's job is to provide one.\n\n**Use when**: The spec is concrete and the work is mostly mechanical.\n\n### 📚 Librarian (DeepSeek v4-flash)\n\nReads long reference documents (design docs, ADRs, journals) and extracts the parts relevant to a query, with hard constraints quoted verbatim. Routing the document via `file_path` keeps it out of the orchestrator's expensive context entirely.\n\n**Use when**: You'd otherwise be reading a 14 KB design doc to find three constraints.\n\n### 🔍 Reviewer (DeepSeek v4-pro)\n\nJudges whether code matches a spec — pass / concerns / fail, with a structured findings list. Not a refactoring or style review; the Reviewer's job is fidelity to the spec, not improvement of the code.\n\n**Use when**: Worker code arrived and you need a second opinion on whether it satisfies the requirements.\n\n### 📝 Scribe (DeepSeek v4-flash)\n\nDrafts commit messages and PR bodies from a `git diff` plus the issue body, following the project's Conventional Commits + co-author conventions. Routine drafting from structured input.\n\n**Use when**: A change is ready to commit and you'd otherwise hand-type the message.\n\n---\n\n## Quality gates\n\nCheap models make mistakes. Maestro's job is to catch them before you do.\n\n- **Structured reasoning**: Every worker returns its output alongside its reasoning and a \"concerns\" section. The conductor sees what the worker was uncertain about.\n- **Test-driven dispatch**: For implementation tasks, the Architect writes tests first, dispatches the implementation, and runs the tests automatically.\n- **Auto-review**: Coder output is reviewed by the Reviewer against its spec before integration — a reviewer pass is mandatory before merge.\n- **Full audit log**: Every dispatch, every response, every token count is logged to `~/.maestro/logs/`. Query the JSONL directly, or browse it in the Web UI.\n\n---\n\n## Quick start\n\n### 1. Download the binary\n\nMaestro ships as a single-file native binary — no Python, no `pip`, no virtualenv. Grab the artifact for your OS from the [latest release](https://github.com/kmeng/maestro/releases/latest):\n\n| OS                            | Artifact                       |\n| ----------------------------- | ------------------------------ |\n| macOS (Apple Silicon)         | `maestro-macos-arm64.tar.gz`   |\n| Linux x64                     | `maestro-linux-x64.tar.gz`     |\n| Windows x64                   | `maestro-windows-x64.zip`      |\n\nExtract the archive and put `maestro` somewhere on your `PATH`:\n\n```bash\n# macOS / Linux\ntar -xzf maestro-macos-arm64.tar.gz\nsudo mv maestro /usr/local/bin/\n\n# Windows (PowerShell)\nExpand-Archive maestro-windows-x64.zip\nMove-Item maestro\\maestro.exe \"$env:USERPROFILE\\bin\\\"\n```\n\n\u003e **macOS first run**: the binary is currently unsigned (code-signing is planned). macOS Gatekeeper will say *\"developer cannot be verified\"*. Bypass once: right-click `maestro` in Finder → Open → Open in the dialog. Future runs work normally.\n\n### 2. Configure your API keys\n\nMaestro reads provider credentials from `.env` (in your project root) or from your shell environment. The minimum is one of `DEEPSEEK_API_KEY` / `DASHSCOPE_API_KEY` / `ANTHROPIC_API_KEY`:\n\n```bash\n# .env in your project root, or export to your shell\nDEEPSEEK_API_KEY=sk-...\n```\n\nGet a DeepSeek key at [platform.deepseek.com](https://platform.deepseek.com); the free signup credit is plenty to bootstrap with.\n\nThe role-to-model mapping has defaults that work out of the box (DeepSeek v4-pro for judgment-heavy roles, v4-flash for extraction). To override per-role, drop a `team.yaml` in your project root — see [the team config guide](docs/architecture.md) for the schema.\n\n### 3. Register with Claude Code\n\n```bash\nmaestro install\n```\n\nThis writes (or updates) `~/.claude/mcp.json` with a `maestro` entry pointing at the binary. Flags:\n\n- `--force` — overwrite an existing maestro entry without prompting\n- `--dry-run` — preview the change without writing\n- `--config-path \u003cpath\u003e` — override the target (advanced / testing)\n\n### 4. Restart Claude Code, then verify\n\nAfter install, **restart Claude Code** so it picks up the new MCP server (see [the upgrade guide](docs/ops/mcp-reload.md) for why this is needed). Then in any Claude Code session run:\n\n```\n/mcp\n```\n\nYou should see `maestro` listed as **connected** with 6 tools: `coder`, `librarian`, `reviewer`, `scribe`, `verifier`, `spec_writer`.\n\n### Upgrading\n\nWhen a new release comes out: download the new artifact, replace the binary on PATH, and **restart Claude Code** (the MCP tool-list is cached per session — same reload story as the first install).\n\n### Use it\n\nJust talk to Claude Code normally. Maestro tools are available as `mcp__maestro__*` and the conductor will dispatch automatically. To make delegation more aggressive, drop this in your project's `CLAUDE.md`:\n\n```markdown\nThis project uses Maestro. Delegate execution-heavy work to the team:\n- Spec-driven implementation → coder\n- Long-doc context extraction → librarian\n- Code review against spec → reviewer\n- Commit messages and PR bodies → scribe\n- Reserve your own attention for architecture, integration, and review.\n```\n\n---\n\n## What you'll see\n\nA typical session looks like this:\n\n```\nYou: Build a REST API for a workout tracker. Users can log workouts,\n     share them with friends, and see a feed of friends' workouts.\n\nArchitect (you, in Claude Code):\n  Let me first get the requirements straight.\n  → Dispatching to librarian to extract the spec hard constraints...\n\n  [Maestro: librarian (deepseek-v4-flash) — 2.4s, $0.001]\n  Returned 3 hard constraints + section-by-section summary.\n\n  Reviewing the spec... I'll structure this as: users, workouts,\n  follows, feed. Let me write the data model and tests first.\n\n  [Architect writes models.py and test_workouts.py — Opus]\n\n  Now dispatching the routine implementation:\n  → Dispatching to coder (3 endpoints, 1 dispatch)...\n\n  [Maestro: coder (deepseek-v4-pro) — 6.1s, $0.002]\n  Returned 3 endpoint handlers. Concerns: \"Used basic auth check;\n  recommend reviewing if more granular permissions needed.\"\n\n  Running tests... 7/7 pass. Reviewing the auth concern — the spec\n  is fine for v1, deferring. Drafting the commit:\n\n  → Dispatching to scribe...\n\n  [Maestro: scribe (deepseek-v4-flash) — 2.8s, $0.001]\n  Returned commit message + PR body draft.\n\n  Done. Total: $0.004, 11.3s.\n  Equivalent pure-Opus run estimate: ~$0.18.\n```\n\nEvery step shows what was dispatched, what came back, what it cost, and how the conductor reasoned about it. Nothing is hidden in a black box.\n\n---\n\n## Project status\n\nMaestro is past MVP and used daily by the maintainers. **v1.0.1 is the latest release** (single-file binaries for macOS / Linux / Windows). The foundation release (v0.0.3) shipped the four core roles, structured audit logging, and the auto-review quality gate; v0.0.4 added the Web UI cockpit and two shadow-mode roles (`verifier`, `spec_writer`); v1.0.0 added the CI quality gate and dashboard accuracy fixes (team-aware overview, applied-projects list, all-pages version display); v1.0.1 added the visual brand (logo + slogan), an About page (community feedback entry), and a README community section.\n\n- ✅ MCP server with 6 worker tools — four promoted (`coder`, `librarian`, `reviewer`, `scribe`) + two shadow-mode (`verifier`, `spec_writer`)\n- ✅ DeepSeek (v4-pro / v4-flash) providers; Anthropic + Qwen pluggable\n- ✅ Structured reasoning + concerns from every worker\n- ✅ Audit logging to JSONL + per-dispatch cost telemetry\n- ✅ Auto-review quality gate (a reviewer pass is mandatory before merge)\n- ✅ Web UI cockpit (`/`, `/team`, `/wizard`, `/scaffold`, `/live`, `/history`, `/savings`, `/problems`)\n- ✅ Single-file binary packaging + GitHub Releases distribution (macOS / Linux / Windows)\n\nEach release is documented in [`docs/journal/`](./docs/journal/); end-of-epic summaries with worker-level cost telemetry land in [`docs/savings.md`](./docs/savings.md).\n\n---\n\n## Design principles\n\nThese are the rules we use when making design decisions. They're worth stating because they're what makes Maestro different from other multi-agent frameworks.\n\n1. **The conductor is always a frontier model.** Cheap models make worse routing decisions than they make code. Don't try to save money on the orchestrator.\n2. **Specs over personas.** A \"Product Manager\" role isn't valuable because it pretends to be a person — it's valuable because it produces structured specs. Roles are defined by their outputs, not their job titles.\n3. **Transparency by default.** Every dispatch is logged. Every worker explains its reasoning. If you can't tell why a piece of code came out the way it did, the system has failed.\n4. **Quality gates, not blind trust.** Cheap models are tools, not teammates. They get reviewed and tested like any other untrusted input.\n5. **Native to Claude Code, not a replacement for it.** Claude Code already nailed the orchestrator UX (permissions, diffs, worktrees). Maestro extends it; it doesn't compete with it.\n\n---\n\n## FAQ\n\n**Is this against Anthropic's Terms of Service?**\nNo. Maestro uses Claude Code as its orchestrator via the standard MCP protocol — exactly what MCP was designed for. Your Claude subscription token never leaves Claude Code's process. The cheap-model API calls go directly from Maestro to the provider using your separate API keys.\n\n**Why MCP instead of just calling models from a Python script?**\nBecause Claude Code's UI, permission system, file diffs, worktree integration, and conversation memory are already excellent. Reinventing that stack is a multi-year project. MCP lets Maestro inherit all of it for free.\n\n**What if I want to use OpenAI / Gemini / local models?**\nAny provider with an OpenAI-compatible endpoint works out of the box (this includes local servers like Ollama). Set the worker's `model:` in your `team.yaml` to the provider's model ID — see the team config schema in [`docs/architecture.md`](docs/architecture.md).\n\n**Can I add my own roles?**\nYes. Roles are defined as YAML + a system-prompt template. See the team config schema in [`docs/architecture.md`](docs/architecture.md).\n\n**How do I know it's actually saving money?**\nStart the Web UI (`maestro webui`) and open the **`/savings`** page — it shows cost per task and per role, plus total saved versus a pure-flagship-model estimate. The same measured data lives in [`docs/savings.md`](docs/savings.md).\n\n---\n\n## Contributing\n\nMaestro is in the phase where contributor input shapes the architecture. If you want to help:\n\n- **Try it on a real project for a week**, then open an issue describing what worked and what didn't. This is the most valuable contribution right now.\n- **Add a provider**: any LLM provider with an OpenAI-compatible API takes ~50 lines.\n- **Propose a role**: open an issue with the role's purpose, ideal model, and example dispatches.\n- **Improve quality gates**: this is the hardest and most important problem. If you have ideas about catching cheap-model errors, we want to hear them.\n\nSee [`docs/governance.md`](docs/governance.md) for the full contribution and workflow guide.\n\n---\n\n## Community / Contact\n\nMaestro is built and maintained by **挖宝的瓦力**. Follow along, get help, or share feedback:\n\n\u003ctable\u003e\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cb\u003eWeChat Official Account\u003c/b\u003e\u003cbr\u003e\n\u003cimg src=\"maestro/webui/static/qr-wechat-mp.jpg\" width=\"180\"\u003e\u003cbr\u003eMethodology \u0026amp; updates\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cb\u003eWeChat (personal)\u003c/b\u003e\u003cbr\u003e\n\u003cimg src=\"maestro/webui/static/qr-wechat-personal.jpg\" width=\"180\"\u003e\u003cbr\u003eAdd me for direct feedback\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cb\u003eGitHub\u003c/b\u003e\u003cbr\u003e\n\u003ca href=\"https://github.com/kmeng/maestro/issues\"\u003eIssues\u003c/a\u003e · Star ⭐\u003cbr\u003eBugs, ideas, contributions\u003c/td\u003e\n\u003c/tr\u003e\u003c/table\u003e\n\n---\n\n## License\n\nMIT. Use it however you want.\n\n---\n\n## Credits\n\nMaestro stands on the shoulders of:\n- [Anthropic](https://anthropic.com) for Claude Code and the MCP protocol\n- [DeepSeek](https://deepseek.com), [Alibaba Qwen](https://qwen.ai), and the broader open-model ecosystem for making cost-effective AI possible\n- The MetaGPT, ChatDev, and CrewAI projects for proving multi-agent orchestration works — Maestro learns from what they got right and what they got wrong\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkmeng%2Fmaestro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkmeng%2Fmaestro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkmeng%2Fmaestro/lists"}