Content
# 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.*
