Skip to main content

Requirements

  • Node.js 22.18 or newer.
  • For agents on Claude: an ANTHROPIC_API_KEY in the environment.
  • For agents on Codex: the Codex CLI, installed and signed in. No Anthropic key is needed. See Runners.

Install

Maestro is not published to npm. Clone the repository and build it.
The command is node bin/maestro from the repository root. Do not use npx maestro: that downloads an unrelated npm package with the same name.

A first workflow

Save this as review.js. It looks for problems in a change from two angles, then asks two skeptics to try to refute each finding. A finding survives only if no skeptic refutes it.
A script starts with export const meta and ends with a top-level return. Everything between is ordinary JavaScript plus the functions Maestro provides. Writing workflows describes them.

Try it without spending anything

--dry-run replaces every agent with a fake that answers from the schema. Nothing goes to the network.
Progress is printed to stderr as a tree of phases and agents. The script’s return value is printed to stdout as JSON.

Run it for real

Agents run in the current directory and can read it. --budget 300k stops the run from spending more than about 300,000 output tokens. See Runs, resume and budget. Maestro writes its state under .maestro/ in the directory you run it in. Add .maestro/ to that repository’s .gitignore.

Change the script and run again cheaply

Every run has an id, printed when it starts. Resume reuses the answers of every agent() call that did not change.
Only the calls you changed, and the calls that depend on their answers, run again.

Look at a run

runs lists the runs in this directory, show prints one run’s agents and outcome, and viz opens a timeline of the run in the browser.

Next

  • Writing workflows for the full script API.
  • Claude Code to let Claude write and start workflows for you.
  • The examples/ directory: review-changes, find-edge-cases and fanout-writers, each runnable with node examples/<name>.js --dry-run.