Home

maestro Wiki

English | 日本語

Paste a GitHub or Linear issue. Get a pull request.

maestro turns issues into reviewable pull requests with multi-agent orchestration on Claude Managed Agents. An orchestrator decomposes work, implementers write code, and everything lands as one PR — with a full audit trail.

Start here

Goal	Page
Run maestro in under 15 minutes	Installation
Deploy on GCP (Cloud Run + LB + IAP)	Terraform
Understand orchestrator / implementer / poller / MCP	Architecture
Env vars, maestro.config, WebUI settings	Configuration
GitHub MCP, Linear, Figma, custom stdio servers	MCP-Servers
Auth errors, stuck runs, tunnel issues	Troubleshooting

What maestro does

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]

Loading

1. Ingest a parent task from GitHub Issues or Linear
2. Decompose into focused, parallelizable sub-issues
3. Implement via Managed Agents + GitHub MCP
4. Finalize into one human-reviewable PR
5. Audit phases, tool calls, and outcomes in the WebUI

Choose your path

Path A — Local laptop (fastest)

Best for trying maestro on a disposable repo.

1. Create a GitHub App with contents, issues, pull_requests write
2. Install it on a test repository
3. Set ANTHROPIC_API_KEY, GITHUB_APP_ID, and the private key
4. bun install && bun run start → open http://127.0.0.1:3000
5. Start a run from the dashboard

Details: Installation → Local

Path B — Container

Best for a shared host or staging box.

docker build -t maestro:0.1.0 .
docker run --rm -p 3000:3000 \
  -e ANTHROPIC_API_KEY=... \
  -e GITHUB_APP_ID=... \
  -e GITHUB_APP_PRIVATE_KEY_PATH=/secrets/github-app.pem \
  -v /path/to/github-app.pem:/secrets/github-app.pem:ro \
  -v maestro-data:/data \
  maestro:0.1.0

Details: Installation → Container

Path C — Production-ish (ingress + MCP Gateway)

Best when Managed Agents must reach your private MCP servers (Figma, internal tools).

• Separate app hostname and MCP hostname
• MCP Gateway Bearer auth + Anthropic outbound CIDR allowlist
• Optional OIDC for the dashboard

Details: Installation → Production · MCP-Servers

Path D — GCP Terraform

Best for a full production stack on Google Cloud (app + MCP + self-hosted worker + Global HTTPS LB / IAP).

cd terraform/examples/complete
cp terraform.tfvars.example terraform.tfvars
terraform init && terraform apply

Details: Terraform · Installation → GCP Terraform · terraform/README.md

Prerequisites checklist

Before the first run, you need:

• Anthropic API key with Managed Agents access
• GitHub App (not a PAT) installed on the target repo
• App permissions: Metadata: read, Contents: write, Issues: write, Pull requests: write
• Bun 1.3+ (pinned in mise.toml) or the container image
• An open GitHub issue (or Linear issue + Linear MCP configured)

First successful run

1. Open the dashboard → New run
2. Pick owner/repo and an open issue number (or paste the issue URL)
3. Click Run
4. Watch phases and events on the run detail page
5. Review the PR maestro opens on GitHub

Optional: add the repo under Repositories and label an issue agent-run (default) so the poller starts runs without the UI.

Source of truth

Kind	Where
User docs (this wiki)	https://github.com/ca-srg/maestro/wiki
Product overview	README
GCP Terraform modules	terraform/README.md · Wiki · Terraform
Contributor / local tunnel notes	docs/DEVELOPMENT.md
Live E2E harness	docs/e2e-setup.md
Agent coding conventions	AGENTS.md

Stack (short)

• Runtime: Bun + TypeScript
• Agents: Anthropic Claude Managed Agents (coordinator + implementer)
• HTTP / UI: Hono SSR dashboard
• GitHub: GitHub App + official GitHub MCP
• Extensibility: MCP Gateway (stdio → remote MCP)

---

Issue in → optimally decomposed plan → real PR → audit trail. No chat babysitting.