ReinaMacCredy/maestro
181 stars · Last commit 2026-05-29
Agent harness for codebases. Gives Claude Code, Codex, and CI a shared task system, verdict ledger, and state store so agent work is traceable and auditable.
README preview
# 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 