Maestro is a local-first coordination system for human and agent work on a codebase. It keeps durable work items, decisions, sessions, evidence, dispatches, and handbacks in each repository's shared Git root, backed by SQLite and an event log. It is written in TypeScript, runs on Bun, and needs no background service; version 0.108.0 is the first TypeScript release, continuing from the final Rust line at 0.107.x.
The design separates three layers. A mechanism kernel owns the store, event log, sessions, CLI dispatch, plugin loading, and readiness projection, without imposing workflow policy. Plugins add verbs and optional policy gates, which a repository enables or disables in .maestro/config. Recipes and skills supply prompt-first working methods as Markdown, readable through maestro recipe show without copying them into the repository.
Work carries proof. Evidence is layered as source, artifact, installed, live, and journey, and a claim stops at the last proven layer rather than rounding untested links up to completion. Method depth is chosen per task: quickfix for a one-sentence diff with no record, Light for a single session and branch tracked as a work item, and Full for multi-session or high-risk work tracked with a spec, notes, and verification bundle. Decisions are recorded as draft, locked, or superseded, and supersession takes effect only when the replacement is locked.
For multi-agent work, the Supervised Lead Protocol (SLP) runs one workspace per team generation with a Team Supervisor, a Lead, lazily opened Peers, and an Observer seat whose only mutation is a stall note that becomes a nudge to the stuck seat. Work moves through OPEN, ACTIVE, RETURNED, and DONE, with the Lead accepting Peer returns and the Team Supervisor accepting the Lead's. SLP is a cooperative protocol rather than a shell sandbox: Maestro checks operations at their supported boundaries but does not block native commands or direct calls.
Attention and briefing are computed at read time rather than delivered as messages. maestro attention detects stalled leases, repeated failures, stale decisions, scope collisions, unreturned dispatches, and unreviewed handbacks in the current repository; maestro brief reads a registry of projects, opens each in observer mode, and reports only what needs attention. A read-only mode (MAESTROREADONLY=1) allows inspection while failing mutations closed.
Features
- Local-first store: SQLite plus an event log in the repository's Git root, with no background daemon
- Three-layer design: a policy-free kernel, plugins that add verbs and gates, and Markdown recipes and skills
- Layered proof: source, artifact, installed, live, and journey evidence, with claims capped at the last proven layer
- Method depth: quickfix, Light, and Full tracks matched to risk and session count
- Durable decisions: draft, locked, and superseded records with rationale and work links
- SLP teams: supervised team generations with Team Supervisor, Lead, Peers, and a nudge-only Observer seat
- Dispatch and handback: stored lane contracts and shape-checked return packets covering dependency, council, challenge, reopen, and failure outcomes
- Search and glossary: search across work, decisions, notes, terms, memory facts, events, and bundles, locally or across the hub
- Attention and brief: read-time detection of stalls, repeated failures, stale decisions, and scope collisions across registered repositories
- Harness adapters: install writes managed adapters and hook entries, and points agents at status, ready work, and recipes through CLAUDE.md and AGENTS.md blocks
- Observer mode: MAESTROREADONLY=1 permits inspection while mutations fail closed and search fails closed rather than returning stale results
- Rust-era import: preserved Rust stores import read-only, or with --promote into native work, decisions, and provenance notes
