npm package: @rajat-rastogi/maestro
Description: Conduct your codebase — autonomous AI coding orchestrator
Author: Rajat Rastogi
Latest version: 0.7.1

<p align="center">
  <img src="assets/logo.png" width="160" alt="Maestro" />
</p>

# 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

```sh
npm install -g @rajat-rastogi/maestro
```

---

## Quick Start

**1. Write a plan file** (`docs/plans/my-feature.md`):

```markdown
# 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:**

```sh
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

```markdown
# 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 | — |
| `--gui` | Open Maestro desktop GUI (Electron app) | — |
| `--install-agent` | Set up this machine as a Maestro remote agent | — |
| `--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:

```sh
maestro --config     # opens browser-based editor
```

Or edit `~/.config/maestro/config` directly (INI format).

---

## AI Providers

### Claude Code

```sh
npm install -g @anthropic-ai/claude-code
claude login
```

Set in config: `ai_provider = claude`.

### GitHub Copilot

```sh
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.

---

## Desktop GUI

Maestro includes an Electron-based desktop GUI with a live terminal grid for managing
AI coding sessions across multiple machines.

```sh
maestro --gui
```

On first run, GUI dependencies (Electron, xterm.js, etc.) are installed automatically.

Features:
- **Terminal grid** — 3-column view with miniature xterm.js previews of all sessions
- **Fullscreen overlay** — click any tile for a full interactive terminal
- **Session state tracking** — real-time Working / Waiting / Idle / Input Required badges
- **Machine management** — add remote dev boxes, monitor online status
- **Create Terminal wizard** — launch Claude or Copilot sessions on any machine

---

## Remote Agent

Run AI coding sessions on remote machines (e.g. Azure Dev Boxes) from your local Maestro GUI.

### Setup (one-time, on the remote machine)

Open **PowerShell as Administrator** on the remote machine and run:

```sh
npm install -g @rajat-rastogi/maestro
maestro --install-agent
```

The setup wizard handles everything:
1. Installs devtunnel (Microsoft Dev Tunnels)
2. Creates a tunnel with port forwarding
3. Installs the agent (WebSocket server + PTY management)
4. Deploys Claude Code hooks for session state tracking
5. Registers a Scheduled Task for auto-start on login

After setup, enter the Tunnel ID in Maestro's Machines view and click **Save & Ping**.

---

## --docs

```sh
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.