Maestro

Autonomous AI coding orchestrator. Maestro reads a markdown plan file, executes each task using a fresh Claude Code or GitHub Copilot session, validates after every step, commits the result, and runs a multi-phase code review — all without human intervention.

How It Works

Plan File  →  Phase 1: Tasks  →  Phase 2: First Review  →  Phase 3: Second Review  →  Phase 4: Finalize
               (N tasks,           (single agent,            (multi-agent,               (optional
                validate +          broad pass)               targeted pass)               cleanup)
                commit each)

1. Parse — Maestro reads your markdown plan and extracts tasks (checkboxes) and validation commands.
2. Execute — Each task is sent to a fresh AI session. The session runs until all checkboxes are marked complete.
3. Validate — After each task, shell validation commands run. On failure, a retry is triggered (up to task_retry_count).
4. Commit — A git commit is made after each successful task.
5. Review — Two review phases run over the full diff: Phase 2 catches broad issues, Phase 3 runs multiple specialist agents on targeted concerns.
6. Finalize — Optional cleanup pass (disabled by default).

Prerequisites

• Node.js ≥ 22
• Git
• At least one AI provider:
  • Claude Code: npm install -g @anthropic-ai/claude-code — then claude login
  • GitHub Copilot: npm install -g @github/copilot — then gh auth login

Installation

npm install -g @rajat-rastogi/maestro

Quick Start

1. Write a plan file (docs/plans/my-feature.md):

# Plan: Add greeting endpoint

## Overview
Add a /greet route that returns a personalised JSON greeting.

## Validation Commands
- `npm run build`
- `npm test`

### Task 1: Create the route handler
- [ ] Create `src/routes/greet.ts` with a `GET /greet?name=` handler
- [ ] Export `greetRouter` from the file
- [ ] Add unit test in `src/routes/greet.test.ts`

### Task 2: Wire into Express app
- [ ] Import `greetRouter` in `src/app.ts`
- [ ] Register at `/greet` before the catch-all handler

2. Run it:

maestro docs/plans/my-feature.md

3. Watch the output — each task is executed, validated, and committed automatically. When all tasks are done Maestro prints ALL_TASKS_DONE and kicks off the review phases.

Plan File Format

# Plan: <Title>

## Overview
One-paragraph description of the goal.

## Validation Commands
- `command that must pass after every task`
- `another command`

### Task 1: <Title>
- [ ] Specific, verifiable deliverable
- [ ] Another deliverable

#### Validation Commands
- `command that only runs after this task`

### Task 2: <Title>
- [ ] Deliverable

Rules:

• ## Validation Commands (top-level) — runs after every task.
• #### Validation Commands (under a task) — runs only after that task.
• Each checkbox must be a specific, observable outcome — Claude marks it [x] when done.
• Every task should leave the codebase in a compilable, passing state.

CLI Reference

Configuration

Maestro merges configuration from four layers (highest priority first):

1. CLI flags — --provider, --max-iterations, etc.
2. Project config — .maestro/config in the current working directory
3. Global config — ~/.config/maestro/config
4. Embedded defaults — shipped inside the package

Config files use INI format. You only need to set keys that differ from the defaults.

Config Keys

Edit your global config:

maestro --config     # opens browser-based editor

Or edit ~/.config/maestro/config directly (INI format).

AI Providers

Claude Code

npm install -g @anthropic-ai/claude-code
claude login

Set in config: ai_provider = claude.

GitHub Copilot

npm install -g @github/copilot
gh auth login

Set in config: ai_provider = copilot (this is the default).

Web Dashboard

All dashboards run locally on http://localhost:8080 (or your configured port).

Writing Good Plans

A few key tips (run maestro --plan-tips for the full guide):

• Validation must pass at every step — not just when all tasks are done. Use conditional checks (existsSync) if a file is created by a later task.
• Checkboxes are verifiable outcomes — write Create src/foo.ts with exported bar() not Work on the foo module.
• Each task should leave the build green — no intentionally broken intermediate states.
• Prefer independent tasks — tasks that don't depend on files from other tasks are safer, easier to retry, and useful with --tasks-only.
• Sequential dependencies — if Task 3 imports a file created by Task 1, use the incremental validation pattern so Task 2 doesn't fail.

--docs

maestro --docs

Opens the full reference documentation (this content, as a formatted HTML page) in your default browser — no internet connection required, served from the local install.