Library

Maestro is an ES module named maestro-orchestrator. It is not on npm; install it from a clone, after npm run build there:

npm install /path/to/maestro

Running a workflow

import { attachTerminalProgress, run } from 'maestro-orchestrator';

const handle = run({ scriptPath: 'review.js', args: { diffRef: 'main...HEAD' }, budget: 300_000 });
const detach = attachTerminalProgress(handle);   // progress tree on stderr
const result = await handle.promise;             // the script's return value
detach();

run() returns at once with a handle:

Field	Meaning
`runId`	The run’s id.
`runDir`	The run’s directory.
`promise`	Resolves with the script’s return value. Rejects on a setup error, a throw in the script, or `stop()`.
`events`	An `EventEmitter`.
`stop(reason?)`	Stops every running agent. The promise rejects with code `run_stopped`.
`skip(agentId)`	Skips one running agent. Its `agent()` call returns `null`.

Options

Option	Meaning	Default
`script`, `scriptPath`, `name`	Exactly one: the script text, a file, or a workflow saved in `workflowsDir`.
`args`	The script’s `args`.
`resumeFromRunId`	Resume this run. The script may then be left out.
`runner`	The runner.	`new AnthropicRunner()`
`cwd`	The agents’ working directory and git repository.	`process.cwd()`
`stateDir`	Where runs are stored.	`<cwd>/.maestro`
`workflowsDir`	Where `name` and `workflow('<name>')` are looked up.	`<stateDir>/workflows`
`tools`	Custom tools, as objects.
`toolsDir`	A directory of custom tool files.	`<stateDir>/tools`
`budget`	A number of output tokens, a shared `Budget`, or `null` for no limit.	`null`
`concurrency`	How many agents may run at once.	CPUs minus 2, at most 16
`model`	The run’s model.	`claude-opus-5-5`
`runId`	An id of your choice.	Generated

Events

Every event is emitted under its own type name and under 'event'.

handle.events.on('agent_end', (e) => console.error(e.label, e.status, e.usage.output_tokens));

Event	When
`agent_start`	An agent starts. Carries `id`, `key`, `label`, `phase`.
`agent_end`	An agent ends. Adds `status`, `cached` and `usage`.
`phase`	The script calls `phase()`.
`log`	The script calls `log()`, or Maestro reports something.
`budget_tick`	Budget use changes. Carries `spent`, `total`, `remaining`.

Runners

import { AnthropicRunner, CodexRunner, FakeRunner, RoutingRunner, run } from 'maestro-orchestrator';

await run({ scriptPath: 'review.js', runner: new CodexRunner() }).promise;

AnthropicRunner({ client?, maxTurns?, maxTokens?, structuredMode? })
CodexRunner({ model?, ignoreUserConfig?, customToolsMcp? })
RoutingRunner({ anthropic?, codex?, route? })
FakeRunner, for tests and dry runs: it answers from the schema and never touches the network.

See Runners.

Giving the Workflow tool to your own agent

If you run your own agent loop on the Claude API, you can hand it the same Workflow tool Claude Code gets.

import Anthropic from '@anthropic-ai/sdk';
import { handleWorkflowToolCall, maestroToolDefinition, toToolResultBlock } from 'maestro-orchestrator';

const client = new Anthropic();
const tools = [maestroToolDefinition() /* , your other tools */];

// When the model calls the Workflow tool:
const res = await handleWorkflowToolCall(toolUse.input, {
  cwd: repoDir,
  budget: 500_000,
  onComplete: (runId, outcome) => queueForModel(runId, outcome),   // give the result to the model on a later turn
});
messages.push({ role: 'user', content: [toToolResultBlock(toolUse.id, res)] });

maestroToolDefinition() returns the tool definition. Its description tells the model when a workflow is worth starting and when it is not.
handleWorkflowToolCall() validates the call, starts the run in the background and returns at once. A bad call returns { is_error: true, content }; it does not throw.
The result arrives through onComplete as { ok: true, result } or { ok: false, error }.

Runs started this way are controlled by id:

import { liveWorkflowAgents, skipWorkflowAgent, stopWorkflowRun } from 'maestro-orchestrator';

liveWorkflowAgents(runId);        // [{ id, label, phase, group }], or null once the run has ended
skipWorkflowAgent(runId, id);     // that agent() returns null, the run goes on
stopWorkflowRun(runId, 'enough'); // running agents are recorded as skipped, onComplete gets ok: false

All three return false or null for an unknown or finished run.

One budget for several runs

To make your main loop’s workflows share one pool, create a Budget and pass the same instance to every call:

import { Budget } from 'maestro-orchestrator';

const budget = new Budget({ total: 2_000_000 });
await handleWorkflowToolCall(input, { budget });

Reading runs

import { readEntries, readOutcome, readTrace } from 'maestro-orchestrator';

const rows = await readEntries(runDir);     // the journal's rows
const outcome = await readOutcome(runDir);  // { ok, result } or { ok: false, error }; undefined while running

Get started

Workflows

Using Maestro