maestro

Local-first harness for agent-built codebases. Humans steer, agents execute, maestro is the substrate.

maestro is a single Rust binary that gives a coding agent a durable place to work. Every unit of work, what is being built, who is doing it, and the proof it was done, lives as plain files under .maestro/ in your repo. No daemon, no hidden service state, no cloud. The agent runs the lifecycle through the CLI; you review the artifacts.

Why

Coding agents are fast but forgetful. They lose the thread across sessions, ship work that was never verified, and leave no trail you can audit. maestro fixes that by making the work itself durable and gated:

• A feature carries the product contract and walks a real lifecycle: proposed -> ready -> in_progress -> shipped.

• A task cannot be called done until its claim is backed by proof that you can read.

• QA (baseline plus slices) gates a ship, so "shipped" means covered, not just compiled.

• Decisions are recorded as files, so the why survives the agent's context window.

Everything is repo-local and reviewable in a diff.

Lifecycle

Features, tasks, and harness improvements each walk an explicit, gated state machine. The agent drives the transitions through the CLI; the gates are enforced, not advisory.

A feature carries the product contract:

stateDiagram-v2
    [*] --> proposed: feature new
    proposed --> ready: accept
    ready --> in_progress: start
    in_progress --> shipped: ship
    proposed --> cancelled: cancel
    ready --> cancelled: cancel
    in_progress --> cancelled: cancel
    shipped --> [*]: archive
    cancelled --> [*]: archive

accept is gated on a frozen contract plus a behavior baseline. ship is gated on no live child tasks plus QA coverage. amend grows a frozen contract additively with an audit reason.

A task is a unit of work, gated by proof:

stateDiagram-v2
    [*] --> draft: create
    note right of draft : created directly, under a feature, or spawned by harness apply
    draft --> in_progress: claim
    in_progress --> needs_verification: complete
    needs_verification --> verified: verify
    in_progress --> abandoned: abandon
    needs_verification --> rejected: reject
    verified --> [*]: archive

The task is the shared unit of work: a feature spins off child tasks (task create --feature) and the harness spins off a standalone task (harness apply), both landing here in draft. claim fast-tracks the internal accept steps when the feature contract or task checks are present (a standalone task needs at least one --check first). verify is the evidence gate: it passes only when the claim is backed by recorded proof.

A harness improvement is a self-improvement proposal the harness surfaces from the run log and task history; it walks its own lifecycle behind features and tasks:

stateDiagram-v2
    [*] --> proposed: detector
    proposed --> accepted: apply
    accepted --> measured: measure (friction gone)
    accepted --> proposed: measure (ineffective)
    measured --> proposed: regressed

apply accepts a proposal and spawns a linked task, so the fix runs through the task lifecycle above. measure re-runs the originating detector to close the loop: it reaches measured only when the friction is actually gone, reverts to proposed if the fix was ineffective, and reopens a measured item if the friction later returns. measure requires the linked task verified unless --force.

How the three fit together

Features and the harness are the two things that produce tasks, and both only reach their terminal state once those tasks are verified. The task lifecycle is the hub:

flowchart TB
    subgraph feature [Feature]
        F1[proposed] --> F2[ready] --> F3[in_progress] --> F4[shipped]
    end
    subgraph harness [Harness]
        H1[proposed] --> H2[accepted] --> H3[measured]
    end
    subgraph task [Task]
        T1[draft] --> T2[in_progress] --> T3[needs_verification] --> T4[verified]
    end
    F3 -->|"task create --feature"| T1
    H2 -->|"apply spawns"| T1
    T4 -->|"child tasks done + QA"| F4
    T4 -->|"linked task verified"| H3

Install

From source (always works):

git clone https://github.com/ReinaMacCredy/maestro
cd maestro
cargo install --path . --locked

With Cargo, directly from git:

cargo install --git https://github.com/ReinaMacCredy/maestro --locked

Release binary (macOS and Linux, arm64 and amd64):

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

The installer drops the binary in ~/.local/bin (override with MAESTRO_INSTALL_DIR). Verify with maestro version and maestro doctor.

Let your agent set it up

maestro is meant to be driven by your coding agent. The installer wires agent skills and hooks into your repo — including a maestro-setup skill that tunes the harness to your build/test commands and conventions — so the agent learns the lifecycle and records its own work. Point your agent (Claude Code, Codex, or any CLI agent) at the repo and paste:

Set up maestro in this repo: run `maestro init --yes`, then `maestro install --agent claude`
(or `--agent codex`). Then follow the maestro-setup skill it installs to tune the harness to
this repo. Start each session with `maestro status`, then drive the feature and task lifecycle
through the `maestro` CLI from there.

Quickstart

Scaffold the repo and install the agent integration:

maestro init --yes                 # create .maestro/ and extract bundled skills/hooks
maestro install --agent claude     # wire skills + hooks into CLAUDE.md/AGENTS.md (or --agent codex)
maestro doctor                     # check the installation
maestro status                     # resume with the next agent action

The smallest loop is a single task. A standalone task (no feature) carries its own acceptance check, and closes once a recorded run backs its claim:

maestro task create "Patch null deref in parser" --check "regression test passes"  # -> draft
maestro task explore task-001                                # -> exploring
maestro task accept task-001                                 # locks the check -> ready
maestro task claim --next                                    # -> in_progress
maestro task complete task-001 --summary "guard the None case" \
  --claim "cargo test parser passes" --proof "observed: cargo test parser passes"

task complete records the inline proof and runs task verify automatically. If the proof is missing or stale, the task stays in needs_verification; run maestro query proof <id> for the repair path.

For a larger change, wrap the work in a feature contract and spin off child tasks:

maestro feature new "CSV export"                         # -> proposed
maestro feature set csv-export --acceptance "Export a report to CSV" --area "src/export"

# accept is gated on a captured behavior baseline. The qa-baseline skill writes this
# for you during an agent run; by hand it is just a non-empty file of [bl-NNN] scenarios:
cat > .maestro/features/csv-export/baseline.md <<'EOF'
# Behavior baseline: CSV export

## Scenario Matrix
- [bl-001] Exporting an empty report yields a header-only CSV file.
EOF

maestro feature accept csv-export                        # freeze the contract -> ready
cat > PLAN-csv-export.md <<'EOF'
## Task T1: Implement CSV writer
check: cargo test export passes
EOF
maestro feature prepare csv-export --from PLAN-csv-export.md
maestro task claim --next
maestro task complete task-001 --summary "wrote csv writer" \
  --claim "cargo test export passes" --proof "observed: cargo test export passes"

# ship is gated on QA coverage: every [bl-NNN] baseline scenario needs a proven slice.
# The qa-slice skill writes this for you; by hand it maps each scenario to its evidence:
cat > .maestro/features/csv-export/qa-slices.yaml <<'EOF'
slices:
  - scenarios: ["bl-001"]
    evidence: ["cargo test export::empty_report_header_only passes"]
EOF

maestro feature ship csv-export --outcome "Shipped streaming CSV export"   # -> shipped

maestro feature show <id> and maestro task show <id> render the current state and the recorded reasoning at any point.

maestro surfaces improvement proposals once it has enough run history to spot friction, so a fresh repo shows none (harness list -> "no improvement proposals found"). The hb-001 below is illustrative; once the backlog has a real entry, run it through the same task loop:

maestro harness list                       # what friction the run log surfaced
maestro harness apply hb-001                # accept a proposal -> spawns a standalone task
maestro task set task-003 --check "deflake the integration suite"   # standalone tasks need a check first
maestro task explore task-003
maestro task accept task-003
maestro task claim --next
maestro task complete task-003 --summary "stabilized the suite" \
  --claim "cargo test integration passes" --proof "observed: cargo test integration passes"
maestro harness measure hb-001              # close the loop once that task is verified

harness apply spawns a standalone task, so it needs a --check before you can claim it. harness measure will not mark the improvement measured until that linked task is verified (pass --force to close it anyway).

Suggested workflow

The three lifecycles compose into one operating rhythm. The Quickstart above is the terse command path; this section narrates it — the agent prompt you hand off for each flow, and what the run