Maestro breaks your project into blocks, decides how risky each one is, and sends each block to the right model — in Claude Code, in Codex, or in any CLI via Adapter SDK. Persistent memory, typed handoffs and universal harness-agnostic protocol.
Mechanical work, no decisions: repetitive code, migrations from a ready schema, test data, conversions, bulk renaming, documentation.
The bulk of construction: business rules, documented integrations, new features, edge cases already mapped and review of what was delivered.
Where mistakes get expensive: architecture, contracts between system parts, data modeling and any decision hard to undo later.
And doesn't deliver better. Most of a project's work is routine — it doesn't need the most expensive reasoning model. Maestro classifies each block and uses the cheapest one that can handle it.
That's a healthy division of labor. Maestro measures yours and warns when the expensive model exceeds a quarter of the cost — which almost always means a specification got ambiguous and someone bumped models by reflex, instead of fixing the text.
Ratio based on API pricing from September 2026. Real savings depend on your project's task mix.
The expensive part happens once. The cheap part repeats until the project is done.
It writes the specifications, breaks the project into blocks and defines for each one: the complexity, the model, the files it can touch and how to know it's done.
The plan becomes a file you correct before any line is written. It's the only time an error is still free.
The manager picks the next released block, sends it to the model the plan defined, calls a reviewer who can't edit anything and only then marks it complete.
Version 2.0 adds five layers that make Maestro work with multiple agents, models and harnesses — with no coupling to any of them.
Working, Episodic, Semantic (FTS5 + entities + links) and Procedural Memory. Markdown as source of truth, SQLite as a zero-reconstructible index.
ProviderRegistry usage-aware and capacity-aware. CEV telemetry (Cost-Efficiency-Velocity) per provider, without platform lock-in.
HandoffManager with exactly-once semantics, workstreams with exclusive lease and cross-agent resume. Claude passes to Codex without losing context or double-delivering.
Universal Context Packet (UCP) and Event Protocol (UEP) — harness-agnostic contracts with trust boundaries and built-in PII and credentials scanner.
Manifest, conformance suite and GenericCLI. Any command-line tool becomes an adapter with a JSON. Claude Code and Codex already included and certified.
Delegating work to a cheaper model only works with method. These are the patterns that agent engineering has consolidated — and they come built-in, no configuration needed.
A criterion written this way becomes nearly a one-to-one test case. That's what makes the spec a contract instead of advice.
Pattern from the aerospace industry. Each criterion has explicit subject, number instead of adjective and a single observable behavior. If you can't write the test assertion, the criterion is still vague.
Since each criterion is already a test, the executor writes tests first, sees them fail and implements until they pass. Green test is the only objective signal of done — without it, done is the model's opinion.
Each block runs isolated, getting only its specification and the files it can touch. A full window degrades predictably: the model loses exactly what's in the middle.
Long session is compacted and detail is lost. One commit per completed block, plus the progress file, rebuild the state without depending on conversation memory.
Each block has a round limit. Exceeding it isn't a sign of weak model — it's a sign of ambiguous spec. The system stops and returns instead of making the same error more expensive.
A 2026 study of 138 real repositories showed that model-generated instruction files hurt agent performance. Here, "use clean code" is banned: style is linter work, not context.
A task with uncertain design is split: the strong model designs and writes the spec; the medium one implements. Sending the entire task to the strong model is what inflates cost without improving anything.
The reviewer runs in a separate session with no permission to edit files. They check criterion by criterion, with evidence, and even look for tests that pass without exercising anything.
Working Memory for active context, Episodic Memory for decision history and Semantic Memory for entity search. The SQLite index is zero-reconstructible — there's never corrupt state you can't recover.
Exactly-once semantics guarantee that a handoff between Claude and Codex is never executed twice. Workstream lease prevents two agents from editing the same context at the same time.
With --phase <name>, each project phase has its own plan in plan/<name>/. Old plans keep working without migration — just don't pass the argument.
--parallel dispatches a batch when no block depends on another and the files each can touch are provably disjoint. On any ambiguity, it serializes. Commits always one at a time.
No manual configuration. Setup talks to you, reads what already exists in the repository and builds the plan by itself.
Detects what already exists, asks up to six questions and generates the plan. With --phase <name> creates a parallel plan without touching the existing one
Shows the board and distribution by model. --block <ID> displays all details and block metric history. Runs on your machine, consumes nothing
Executes the next released block and calls the reviewer. --dry-run shows without dispatching; --parallel dispatches up to two blocks at once when there's no file conflict
Writes the specification for a new block with the strong model
Adjusts the plan when reality changes
Shows planned distribution by model and reminds you to check /context and /usage, Claude Code's native cost commands
Recovers blocks interrupted by crash or session compaction — analyzes git and offers to resume, reset or discard
Audit review of any completed block, independent of execution flow
Clears the lock on a block without editing JSON manually. Requires explicit confirmation before saving
Point change in a block's specification, or full regeneration with the strong model. Validates the plan at the end
Undoes an approved block using git revert — never git reset. Checks clean tree before touching anything
Generates plan/REPORT.md with complete state, specifications and metrics. Ready to share with the team
New in 2.0. Migrates legacy structure (v1.x) to the new layer architecture with automatic backup, conversion report and rollback on failure
Delivering work to a cheap model only works with rails. These are checked before any block is dispatched.
Blocks where a mistake is irreversible stay locked to the strong model — both to execute and to review.
The reviewer runs in a separate session with no permission to edit files. They approve or reject, with evidence for each criterion.
If a decision from you is missing, a credential or data, the block stays marked as locked — instead of the model filling the gap on its own.
When the same block fails again, the cause is almost always an ambiguous spec. Bumping the model would only make the same error more expensive.
The Universal Context Packet has a built-in scanner that blocks personal email, phone, CPF, API keys and other secrets before any data leaves the machine.
Exactly-once semantics guarantee that a transfer between agents is never consumed twice — even under true concurrency of multiple processes.
Leave your email and the installation commands appear here instantly. No cost, no card. Works in Claude Code, Codex and any CLI with a JSON adapter.
Done. Run in the terminal, inside your project:
View on GitHub — open source, no server in between.
Claude Code on any paid plan, and a project you already work on. Maestro is not a separate service: it runs inside Claude Code, on your account. Works in the terminal, VS Code, JetBrains and the desktop app.
Yes. Version 2.0 includes the Adapter SDK: any tool with a valid adapter.manifest.json file passes the conformance suite and can execute blocks. Codex is already included and certified. A generic adapter for any CLI also comes out of the box — no plugin needed.
Use headless mode: python integrations/relay/headless_cli.py --headless --dry-run <ID> — returns code 0 or 1, never asks for interactive input. An example workflow for GitHub Actions is in .github/workflows/maestro-ci.yml in the repository.
Yes, as long as work can be broken into blocks with an objective way to say it's done. Research, serial content production and data migration work well. What doesn't fit is work where "done" is a matter of taste.
Yes, because whoever executes is Claude Code with your account. The question is how much: using the right model for each task makes the same build consume well less of your limit.
It doesn't pass through any server of ours. Maestro is a set of text files that runs inside your Claude Code. Plus, version 2.0 adds a PII and credentials scanner in the Universal Context Packet — no sensitive data leaves without being detected first.
You can. Everything is text files in your repository: the agents, the commands and the plan. Edit freely, including which models go into each complexity level.
It's free and open. If you want to give back, use it and tell us what worked and what broke — that's what makes the next version better.