maestro

maestro

Maestro is a local-first agent harness for the spec-to-ship loop. It gives agents one CLI and one on-disk state model for specs, tasks, evidence, contracts, handoffs, and principles so separate sessions can collaborate without a server, database, or background daemon.

In day-to-day use it acts as a conductor: a human operator drives multiple terminals while Maestro keeps the shared state disciplined and inspectable. The vocabulary is spec -> task -> verify -> ship. One task equals one PR (ADR-0006). Multi-PR work decomposes into an exec-plan via maestro plan. See docs/harness-positioning.md for the principle-to-primitive mapping.

Why Maestro

• Shared state lives on disk in .maestro/, not in chat history.
• Specs define acceptance criteria, risk class, and non-goals before code is written.
• Tasks carry durable, per-session continuation records so the next agent resumes exactly where the last left off.
• Handoff envelopes are emitted passively at each lifecycle transition; the next agent reads the file on disk.
• Evidence turns agent claims into auditable, witnessed rows tied to tasks and contracts.
• The trust substrate (contracts, verifier, verdict, CI) gates completion on witnessed evidence, not convention.
• Mission Control gives you a read-only TUI and JSON snapshots of current state.
• The runtime stays local-first: filesystem, git, config, and terminal tools.

System Map

Maestro is the shared state layer in the middle. The operator and fresh agent runs both go through the CLI, the CLI persists shared state locally, and Mission Control projects that same state without mutating it.

What Maestro Is Not

• It is not a hosted orchestration service or remote agent platform.
• It is not tied to a single model vendor or harness.
• It does not require a database, queue, or network API to work.
• It does not schedule or background anything. "Automatic" means computed from the result of the verb the agent just called.

The human operator is the bridge between terminals. Maestro is the shared state layer underneath that workflow.

Core Concepts

Concept	Purpose
Spec	A product-spec markdown file with YAML frontmatter: acceptance criteria, non-goals, risk class, mode, and work type. The input to the task lifecycle.
Task	The atomic unit of work. One task equals one PR. Carries a state machine, continuation record, optional contract, and linked evidence.
Exec-plan	A container for multiple child tasks decomposed from a heavy-mode spec. Auto-completes when all children reach a terminal state.
Evidence	An auditable row tied to a task: command run, exit code, optional log path, and a witness level.
Contract	A machine-checked scope agreement attached to a task: files expected, files forbidden, and explicit done-when criteria.
Handoff	A passive JSON envelope emitted at lifecycle transitions. The next agent reads .maestro/handoffs/<id>.json to learn what happened and why.
Principle	A behavioral rule stored at .maestro/principles.jsonl and injected into agent prompts.
Verdict	The deterministic gating decision after verification: PASS, FAIL, HUMAN, or BLOCK.
Mission Control	A read-only terminal dashboard and JSON snapshot surface for inspecting current state.

How Work Flows

The loop is deliberately simple: author a spec, create a task, claim it, implement and verify in a loop, then ship. Each transition emits evidence and a handoff envelope so any subsequent agent can resume without a briefing.

Installation

Requirements

• Bun
• Git
• A local agent harness in another terminal, such as Codex, Claude Code, or Hermes

Install From Release

Install the latest published Maestro binary:

curl -fsSL https://raw.githubusercontent.com/ReinaMacCredy/maestro/main/scripts/install.sh | bash

Install a specific published release:

MAESTRO_VERSION=<version> curl -fsSL https://raw.githubusercontent.com/ReinaMacCredy/maestro/main/scripts/install.sh | bash

After installation, refresh to the latest published release with:

maestro update

Build From Source

bun install
bun run build

This produces the compiled binary at ./dist/maestro.

Install Locally

bun run release:local
command -v maestro
maestro --version

If you also want to initialize global config and inject supported agent instruction blocks:

maestro install

This syncs bundled Maestro skills into Codex, Claude Code, Hermes, and the shared AgentSkills root when those targets are available. See Provider Registry and Skills for roots, diagnostics, and external skill installs.

./dist/maestro is the fresh repo build. maestro on your PATH is the installed local binary.

Quick Start