maestro

Maestro is a local-first conductor for multi-agent software engineering. It gives you one CLI and one on-disk state model for missions, features, assertions, handoff launches, checkpoints, memory, and project context so separate agent sessions can collaborate without a server, database, or background daemon.

It is designed for a workflow where a human operator coordinates multiple terminals, while Maestro keeps the shared state disciplined and inspectable.

Why Maestro

• Shared state lives on disk in .maestro/, not in chat history.
• Missions break work into milestones, features, and validation assertions.
• Native handoff launches build a self-contained markdown brief and start a fresh Codex or Claude run from the current repo state.
• Memory commands turn corrections and learnings into reusable guidance.
• 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.

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

Two Working Loops

Maestro has two related but separate operating modes:

| Use missions when you need... | Use tasks when you need... | |---|---| | A planned multi-step effort with milestones, assertions, checkpoints, and handoff launches. | A lightweight blocker graph for the daily queue. | | A durable brief for a fresh agent run. | Fast ready, claim, update, and blocker management. | | Reviewable artifacts under .maestro/missions/<mission-id>/. | Repo-tracked task state under .maestro/tasks/tasks.jsonl. |

If you only remember one distinction: mission is for planned execution; task is for the day-to-day queue.

Core Concepts

| Concept | Purpose | |---|---| | Mission | The top-level unit of work with a lifecycle such as draft, approved, or executing. | | Milestone | A phase within a mission. Milestones can act as work phases or validation gates. | | Feature | A concrete piece of work assigned to an agent type, with verification steps and optional dependencies. | | Assertion | A validation target tied to a feature. Assertions are updated to passed, failed, blocked, or waived. | | Handoff | A persisted launch record plus markdown brief for starting a fresh Codex or Claude session from current mission or repo context. | | Task | A Claude-style blocker-graph work item for the daily loop; lives at .maestro/tasks/tasks.jsonl independent of missions. | | Reply | An agent's structured outcome record for a feature, optionally gated by behavioral principles. | | Principle | A behavioral rule injected into agent prompts and scored against replies. Stored at .maestro/principles.jsonl. | | Memory | Corrections, learnings, and compiled guidance that feed back into future agent prompts. | | Checkpoint | A timestamped mission snapshot you can save and later restore. | | Bundle | A portable .mission.tar.gz archive of a mission plus its artifacts for review or transfer. | | Mission Control | A read-only dashboard for previewing mission state interactively or as JSON. |

Mission Control Preview

Mission Control gives you a read-only terminal dashboard over the current Maestro state.

How Work Flows

The loop is deliberately simple: define work, optionally inspect the feature brief, launch a fresh handoff, update progress, validate the outcome, and checkpoint before sealing the milestone.

Installation

Requirements

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

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

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

Quick Start

1. Initialize a project

maestro init

This creates the local .maestro/ workspace for the current repository.

2. Create a mission plan file

mission create expects a JSON plan file. A minimal example:

{
  "title": "Add authentication",
  "description": "Ship the first authentication slice",
  "milestones": [
    {
      "id": "plan",
      "title": "Planning",
      "description": "Define the implementation approach",
      "order": 0,
      "kind": "work",
      "profile": "planning"
    },
    {
      "id": "implement",
      "title": "Implementation",
      "description": "Build and verify the feature",
      "order": 1,
      "kind": "work",
      "profile": "implementation"
    }
  ],
  "features": [
    {
      "id": "auth-plan",
      "milestoneId": "plan",
      "title": "Plan the auth flow",
      "description": "Define the login shape, risks, and acceptance criteria",
      "agentType": "codex-cli",
      "verificationSteps": [
        "Review the proposed flow with the team"
      ]
    },
    {
      "id": "auth-impl",
      "milestoneId": "implement",
      "title": "Implement the auth flow",
      "description": "Build the first working authentication slice",
      "agentType": "codex-cli",
      "dependsOn": [
        "auth-plan"
      ],
      "verificationSteps": [
        "Run build",
        "Run targeted tests",
        "Verify the login flow manually"
      ],
      "fulfills": [
        "auth-login-works"
      ]
    }
  ]
}

3. Create and approve the mission

maestro mission create --file plan.json
maestro mission list
maestro mission approve <mission-id>

4. Inspect the current feature brief (optional)

maestro feature list --mission <mission-id>
maestro feature prompt <feature-id> --mission <mission-id> --out agent-prompt.md

This writes the prompt to agent-prompt.md and also stores it under .maestro/missions/<mission-id>/agents/<feature-id>/prompt.md. maestro handoff does not require this step, but it is useful when you want to inspect the current feature context before launching a fresh agent run.

5. Launch a handoff

Launch a fresh Codex run for the next implementation slice:

maestro handoff \
  "Implement auth-impl for mission <mission-id> and run the listed verification steps before stopping" \
  --agent codex

Launches are detached by default. Maestro persists the handoff under ~/.maestro/handoff/<id>/ (a single global store) and returns the launch record with the prompt path, log path, target directory, linked task id, and agent details.

Useful variants:

maestro handoff "Review auth-impl before merge" --agent claude --worktree auth-review
maestro handoff "Finish auth-impl and wait for the result" --agent codex --wait --json
maestro handoff pickup --id <handoff-id> --json

6. Track progress, validate, and seal

maestro feature update auth-impl --mission <mission-id> --status in-progress
maestro feature update auth-impl --mission <mission-id> --status review
maestro validate show --mission <mission-id>
maestro validate update auth-login-works --mission <mission-id> --result passed --evidence "bun test"
maestro checkpoint save --mission <mission-id>
maestro milestone seal implement --mission <mission-id>

Handoffs

maestro handoff "<task>" builds a self-contained markdown brief from the current repo state plus the linked task continuation, then launches a fresh Codex or Claude run. Every launch is persisted under ~/.maestro/handoff/<id>/ (a single global store) so the operator can inspect exactly what was sent and what the child process printed. Handoffs created in one working directory are visible from any other. Prompt-only packets can be picked up from any working directory, but task-linked packets must be picked up from their source project unless you explicitly pass maestro handoff pickup --standalone.

What a launch contains

A launch record always includes:

• id, agent, and model
• status: launching, launched, completed, or failed
• targetDir: the directory handed to the external agent
• promptPath, outputPath, and the exact launched command
• task and takeover metadata such as refs.taskId, createdByAgent, pickedUpByAgent, and consumedAt
• optional worktree metadata when --worktree is used
• optional pid and exitCode, depending on detached vs --wait mode

The prompt itself is stored separately as markdown. Maestro always renders the same sections:

• Task
• Context
• Relevant Files
• Current State
• What Was Tried
• Decisions
• Acceptance Criteria
• Constraints

How prompt context is chosen

• If exactly one actionable feature exists in the active mission, Maestro anchors the brief to th