maestro

# maestro **English** | [日本語](README_ja.md) **Paste a GitHub or Linear issue. Get a pull request.** maestro is an open-source multi-agent system that turns issues into shipped code — autonomously. An orchestrator **decomposes** the work into the right sub-tasks, specialist implementers write the code, and everything lands as one reviewable PR — with a full **audit trail** of what happened. Built on [Claude Managed Agents](https://docs.anthropic.com/).  <p align="center"> <a href="https://github.com/ca-srg/maestro/wiki">Wiki</a> · <a href="https://github.com/ca-srg/maestro/wiki/Installation">Install</a> · <a href="https://github.com/ca-srg/maestro/wiki/Architecture">Architecture</a> · <a href="#quick-start">Quick Start</a> </p> --- ## Why maestro? Coding agents are great at *writing* code. They're worse at *owning* a ticket end-to-end: scoping it well, splitting it into the right units of work, implementing in parallel, opening a clean PR, and leaving a trail you can audit later. maestro is that missing layer. | You do | maestro does | | --- | --- | | Open a **GitHub** or **Linear** issue | Ingest it as the parent task | | Watch the WebUI | **Optimally decompose** into focused sub-issues (not too coarse, not a mess of tiny slices) | | Review one PR | Implementers ship code; work consolidates into a single pull request | | Ask "what did the agent do?" | **Audit logs + run events** preserve every phase, tool call, and decision | No chat babysitting. No "please continue." Issue in → PR out — and a record of how you got there. ## How it works ```mermaid flowchart LR Issue[GitHub / Linear issue] --> Maestro[maestro] Maestro --> Orchestrator[orchestrator] Orchestrator --> I1[implementer] Orchestrator --> I2[implementer] Orchestrator --> I3[implementer] I1 & I2 & I3 --> PR[Single pull request] ``` 1. **Ingest** a parent task from **GitHub Issues** or **Linear** (identifier or URL). 2. **Orchestrator** plans and **decomposes** into the smallest set of independent, implementable sub-issues — boundaries chosen for parallel work and clean review, not arbitrary chunking. 3. **Implementers** (Claude Managed Agents) pick up each sub-issue and write real code against your repo via GitHub MCP. 4. **Finalize** merges the work into one pull request — ready for human review. 5. **Audit** — structured audit logs and per-run event history capture phases, agent/tool activity, and outcomes for later inspection (WebUI + logs; OpenTelemetry optional). Trigger from the **WebUI**, the **HTTP API**, or a **GitHub repo poller** that watches labeled issues. Same pipeline for Linear origins. ## Screenshots | Start a run | Watch progress | | --- | --- | |  |  | ## What you get - **GitHub Issues and Linear** — same orchestrate → implement → PR path for both origins - **Optimal task decomposition** — orchestrator splits work into focused, parallelizable sub-issues instead of one giant agent loop - **Audit log retention** — structured audit events (HTTP, session, tools) plus durable run-event history you can replay in the WebUI - **Multi-agent by design** — coordinator + implementer roster, not a single long chat - **Real PRs, not diffs in a sidebar** — branches, commits, and a reviewable pull request on your GitHub - **WebUI + API** — kick off runs from the browser or wire it into your own tools - **GitHub App auth** — installation tokens per repo, no shared PAT sprawl - **MCP-native** — GitHub MCP built in; plug in Figma, Linear MCP, or your own stdio servers via the MCP Gateway - **Self-hosted sandboxes** — keep code execution on your infra with `ANTHROPIC_ENVIRONMENT_ID` - **Prompt & repo controls in the UI** — system prompts, polled repos, MCP servers, all editable without redeploying - **OpenTelemetry-ready** — traces and metrics when you want them, off by default ## Quick Start Bun is pinned in [`mise.toml`](mise.toml). Install [mise](https://mise.jdx.dev/), then: ```bash mise install bun install export ANTHROPIC_API_KEY=... export GITHUB_APP_ID=... export GITHUB_APP_PRIVATE_KEY_PATH=/path/to/github-app.pem bun run start # → http://127.0.0.1:3000 ``` Open the dashboard, pick a repo + issue number, hit run. Full setup (GitHub App, containers, MCP Gateway, self-hosted workers) is in the **[Installation wiki](https://github.com/ca-srg/maestro/wiki/Installation)**. Production on **Google Cloud** (Cloud Run + Global HTTPS LB + IAP): **[Terraform wiki](https://github.com/ca-srg/maestro/wiki/Terraform)** / [`terraform/`](terraform/). ## Documentation | Topic | Link | | --- | --- | | Installation | [Wiki · Installation](https://github.com/ca-srg/maestro/wiki/Installation) | | GCP Terraform (Cloud Run app / MCP / worker / edge) | [Wiki · Terraform](https://github.com/ca-srg/maestro/wiki/Terraform) | | Architecture (orchestrator, implementer, poller, MCP Gateway, self-hosted) | [Wiki · Architecture](https://github.com/ca-srg/maestro/wiki/Architecture) | | Configuration | [Wiki · Configuration](https://github.com/ca-srg/maestro/wiki/Configuration) | | MCP servers | [Wiki · MCP-Servers](https://github.com/ca-srg/maestro/wiki/MCP-Servers) | | Troubleshooting | [Wiki · Troubleshooting](https://github.com/ca-srg/maestro/wiki/Troubleshooting) | Local contributor notes: - [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) — dev tunnel and local workflow - [`docs/e2e-setup.md`](docs/e2e-setup.md) — live E2E setup - [`terraform/README.md`](terraform/README.md) — GCP module reference (app, mcp-gateway, worker, edge) ## Stack - **Runtime:** [Bun](https://bun.sh) + TypeScript - **Agents:** Anthropic Claude Managed Agents (multi-agent coordinator) - **HTTP / UI:** [Hono](https://hono.dev) SSR dashboard - **GitHub:** GitHub App + official GitHub MCP - **Extensibility:** MCP Gateway (stdio → remote MCP) ## E2E Tests Live E2E hits real APIs and writes to a disposable repo (billing applies): ```bash E2E=1 TEST_REPO=<owner>/<repo> TEST_ISSUE=<n> bun run scripts/e2e-real.ts ``` ## License See the repository for license details. Contributions welcome — open an issue or PR. --- *Stop pasting tickets into a chat box. Point maestro at a GitHub or Linear issue, get an optimally decomposed plan, a real PR — and an audit trail of every step.*