maestro CLI
maestro keeps work, decisions, sessions and evidence of humans and agents in the shared Git root, locally, with no service
- 235 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The installer downloads and runs a script, writes hooks and blocks into the repository `CLAUDE.md` and `AGENTS.md` and creates a shared store in the home folder.
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/ReinaMacCredy/maestro/main/scripts/install.sh | shNeeds `git` and Bun. The script clones sources into `~/.maestro/source` and runs the installer.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The installer downloads and runs a script, writes hooks and blocks into the repository `CLAUDE.md` and `AGENTS.md` and creates a shared store in the home folder.
This is third-party code. Review the repository files before installing.
What it does
maestro is a command-line coordination system in TypeScript on Bun. It stores durable work, decisions, sessions, evidence, dispatches and handbacks in the shared Git root of each repository. The kernel owns the SQLite store, event log, sessions and command dispatch, while policies plug in as plugins: proof and breakdown gates are switched on or off in `.maestro/config`. The `maestro` command has verbs for the lifecycle: `work add|start|note|done` runs tasks, `decision draft|lock|confirm` records decisions, `dispatch open|accept` and `handback file` pass assignments and results between sessions, and `status`, `ready` and `attention` show state and what needs attention. Working methods are Markdown recipes shown by `maestro recipe list` and `maestro recipe show`. Install configures adapters for Claude and Codex and merges `SessionStart` and `UserPromptSubmit` hooks that record the session and print a short brief. Nine managed skills such as `maestro-work` and `maestro-verify` are materialized under `~/maestro/skills`. For agent teams there is an SLP protocol with Supervisor, Lead and Peer seats.
Who it is for. Developers who run several agents and people in parallel across repositories and want tasks, decisions and evidence in one local store.
Good fit when
- Several agents work on one repository and you need to see who took which task and what is ready to start.
- Important decisions get lost in chats and must be pinned with reasons and confirmation.
- A task has to be handed to another session as a contract and returned with evidence.
- You want ready Markdown work recipes the agent reads with `maestro recipe show`.
Not a fit when
- You need a service with a web UI and background sync: maestro is local and has no service.
- You cannot install Bun and git, and the installer pulls sources from the repository.
- You need a security sandbox for agents: the SLP protocol is cooperative and does not block shell commands.
Example request
Open a task with `maestro work add`, record the decision with `maestro decision draft` and show `maestro ready`.Limitations
Maestro is distributed from source: the installer clones the repository into `~/.maestro/source` and needs `git` and Bun. Version 0.108.0 is the first TypeScript release after the Rust line 0.107.x, and old data is imported with `maestro import rust`. The SLP protocol is built for agent cooperation and is not a sandbox: it checks nine operations at supported boundaries while native commands and direct Herdr calls stay unrestricted. Update accepts only a fast-forward and refuses a dirty or diverged source.
How to disable. Run `maestro uninstall`: it removes managed hooks and blocks from the current repository but keeps data, the runtime and the shim. Delete the runtime and shim by hand.
FAQ
How do I install maestro?
Run `curl -fsSL https://raw.githubusercontent.com/ReinaMacCredy/maestro/main/scripts/install.sh | sh`. `git` and Bun are required. From your own clone `bun bin/maestro.ts install` works.
How do I verify the installation?
Run `maestro doctor`: it checks the shim, runtime, source, repository wiring, permissions and store access and repairs nothing itself.
How do I update?
Run `maestro update`: it fast-forwards the source and resyncs the runtime.
Which agents does it work with?
Claude Code and Codex: install writes managed adapters and hooks for both.
Where is data stored?
In the shared Git root of each repository, in a SQLite store and event log. A Supervisor room is created in `~/maestro`.
Discussion
No questions or reviews yet.
Related
CLI toolsA skill with 25 commands to audit and improve the prompts, tools and agent designs of a project in Cursor, Claude Code and Codex
Maestro-Flow builds a chain from analysis to tests for a goal and runs Claude Code, Codex, Gemini and other agents through it
An orchestration plugin for Claude Code, Codex, Gemini CLI and Qwen Code: 39 specialists, parallel subagents, persistent sessions and standalone audits
A scaffold of personas, rules and skills in plain Markdown: Maestro hands work to different models and spares your main plan
A local Node.js orchestrator that runs Codex, Claude Code, Gemini and OpenCode as one team led by an operator agent
botmux connects Lark and Feishu to Claude Code, Codex, Gemini CLI and OpenCode: each message starts its own agent session with live cards
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| maestro (this card) | no | 235 | |
| maestro-runner | no | 529 | maestro-runner runs mobile app tests, while ReinaMacCredy/maestro coordinates agent work in Git. |
| agent-memory | no | 4,315 | agent-memory keeps agent notes, while here tasks, decisions, assignments and evidence are tracked. |
README in short
The README covers three layers: kernel, plugins and recipes with skills, plus a verb tour, observer mode, adapter setup and contribution rules. MIT license.