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

| Flag | Description | Default | |------|-------------|---------| | [plan-file] | Path to the markdown plan to execute | — | | --provider <name> | AI provider: copilot or claude | copilot | | -m, --max-iterations <n> | Maximum task execution iterations | 50 | | --max-external-iterations <n> | Second-review iteration limit (0 = auto) | 0 | | -r, --review | Skip tasks; run review pipeline on current branch | — | | -t, --tasks-only | Run tasks only; skip all reviews | — | | -b, --base-ref <ref> | Override default branch for review diffs | auto | | --skip-finalize | Skip finalize step | — | | --worktree | Run in an isolated git worktree | — | | --plan <description> | Create a plan file interactively via AI | — | | -s, --serve | Start live web dashboard | — | | --replay | Browse completed runs in offline dashboard | — | | -p, --port <n> | Web dashboard port | 8080 | | -w, --watch <dir> | Extra directory to watch for progress files | — | | -d, --debug | Enable debug logging | — | | --no-color | Disable ANSI color output | — | | --plan-tips | Show plan authoring best practices | — | | --docs | Open full reference documentation in browser | — | | --config | Open web UI to view/edit configuration | — | | --reset | Interactively reset global config to defaults | — | | --dump-defaults <dir> | Extract embedded defaults to a directory | — | | --config-dir <dir> | Override config directory | — |

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

| Key | Default | Description | |-----|---------|-------------| | ai_provider | copilot | copilot or claude | | claude_command | claude | Claude Code executable | | claude_args | (see defaults) | Extra args passed to Claude | | claude_error_patterns | (see defaults) | Patterns that signal a fatal Claude error | | copilot_command | copilot | Copilot executable | | copilot_args | --autopilot --allow-all | Extra args passed to Copilot | | copilot_error_patterns | (see defaults) | Patterns that signal a fatal Copilot error | | max_iterations | 50 | Max AI iterations per task | | max_external_iterations | 0 | Review iteration limit (0 = auto) | | iteration_delay_ms | 2000 | Delay between iterations (ms) | | task_retry_count | 1 | Retries on validation failure | | validation_timeout_ms | 60000 | Validation command timeout (0 = unlimited) | | finalize_enabled | false | Enable Phase 4 finalize step | | use_worktree | false | Run in isolated git worktree | | plans_dir | docs/plans | Default directory for plan files | | default_branch | (auto) | Base branch for review diffs | | vcs_command | git | VCS executable | | push_on_complete | false | Push branch after all phases complete | | port | 8080 | Web dashboard port | | watch_dirs | — | Comma-separated extra dirs for dashboard | | color_task | #00ff00 | Task phase color | | color_review | #00ffff | Review phase color | | color_signal | #ff6464 | Signal color (ALL_TASKS_DONE etc.) | | color_warn | #ffff00 | Warning color | | color_error | #ff0000 | Error color | | color_info | #b4b4b4 | Info / default text color | | color_timestamp | #8a8a8a | Timestamp color |

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

| Command | What it does | |---------|-------------| | maestro <plan> --serve | Live dashboard — streams task progress in real time | | maestro --replay | Offline dashboard — browse completed run logs | | maestro --config | Config editor — view and change all settings in a browser UI |

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.