# Maestro > Spec-driven AI development workflow for the terminal — from idea to reviewed merge. - **Type:** MCP server - **Install:** `agentstack add mcp-bryann2k-maestro` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [BRYANN2K](https://agentstack.voostack.com/s/bryann2k) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [BRYANN2K](https://github.com/BRYANN2K) - **Source:** https://github.com/BRYANN2K/maestro ## Install ```sh agentstack add mcp-bryann2k-maestro ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Maestro Code in Concert. Turn an idea into a reviewed, documented change—without giving up control of your code. Maestro is an open-source, terminal-native AI development environment built around reviewable specs and explicit user control. It turns a conversation into a structured plan, coordinates focused agents to implement it, checks the result, drafts the documentation, and archives the finished work. You decide when each phase begins. ```text idea → spec → build → review → docs → archive ``` ## Why Maestro - **Review the plan before the code.** Maestro turns your intent into a structured spec that you can inspect and accept before implementation starts. - **Stay in control at every boundary.** Proposing, accepting, building, reviewing, documenting, and archiving are separate, explicit actions. - **Use the right model for each job.** Route Chat, Build, Review, and Docs to different models and reasoning levels. - **Keep changes isolated and reviewable.** Builds run in managed Git worktrees, with deterministic checks and read-only review built into the lifecycle. - **Work interactively or automate the flow.** Use the responsive TUI for daily development or the same lifecycle through headless commands in scripts and CI. ## Inside Maestro Independent model routingChoose the model and reasoning effort for each task. One integrated workspaceKeep the project, spec, lifecycle, and implementation together. ## Install ### npm (recommended) The npm package is a small launcher for Maestro's prebuilt release binary. It requires Node.js 18 or newer; it does **not** require a Go toolchain. ```sh npx @bryann2k/maestro ``` The launcher selects the matching macOS, Linux, or Windows binary for the current architecture and caches the exact Maestro version selected by the npm package. Pin `@1.0.0` when reproducibility matters. Arguments are forwarded unchanged: ```sh npx @bryann2k/maestro --dir ./my-project npx @bryann2k/maestro version ``` ### GitHub release binary Download the archive for your operating system and architecture from the [Maestro 1.0.0 release](https://github.com/BRYANN2K/maestro/releases/tag/v1.0.0), verify it against `checksums.txt`, and place `maestro` (or `maestro.exe`) on your `PATH`. Release assets follow this pattern: ```text maestro_1.0.0_darwin_arm64.tar.gz maestro_1.0.0_darwin_amd64.tar.gz maestro_1.0.0_linux_arm64.tar.gz maestro_1.0.0_linux_amd64.tar.gz maestro_1.0.0_windows_arm64.zip maestro_1.0.0_windows_amd64.zip ``` ### Build with Go With Go 1.26.5 or newer: ```sh go install github.com/bryann2k/maestro/cmd/maestro@v1.0.0 ``` ### Update notifications The TUI checks the public npm stable release metadata in the background at most once every 24 hours. When a newer version exists, Maestro shows a quiet, persistent `UPDATE v…` status and points `/update` to the exact npm install command. The check does not delay startup, send telemetry, contact GitHub Actions, or install anything automatically. ```text /update force a fresh check /update status show the current update-check policy /update off disable automatic checks /update on enable automatic checks ``` The same preference is available under `Settings → General → Update checks`. Set `MAESTRO_NO_UPDATE_CHECK=1` for a process-level opt-out. Network and registry failures remain silent during automatic checks; an explicit `/update` reports the failure without exposing response bodies. ## Quick start Run Maestro from the repository you want it to understand: ```sh cd my-project maestro ``` On first use: 1. Open `/providers` and connect an API provider or an existing CLI subscription. 2. Discuss the project naturally. Use `/bootstrap` for a new project or `/adopt` for an existing repository (`/onboard` remains an alias). 3. Invoke `/propose` when the idea is ready to become a spec. If MAESTRO.md is missing, Maestro completes project setup first and resumes the proposal only after you accept the contract. 4. Review and `/accept` the proposal. Maestro creates and selects an isolated managed worktree automatically; then run `/build`. 5. Complete `/review`, `/docs`, and `/archive` when the evidence is ready. Maestro never treats an approximate chat message as permission to create a spec. Only `/propose` crosses that boundary. ## The development lifecycle | Phase | What Maestro does | User control | | --- | --- | --- | | Chat | Explores the repository and clarifies intent | Read-only discovery | | Propose | Creates a structured `spec.md`, `design.md`, and `tasks.md` draft | Explicit `/propose` | | Accept | Validates the spec and creates an isolated managed worktree | Explicit acceptance; Git setup is automatic | | Build | Delegates implementation and tests to a development agent | Tool permissions and cancellation | | Review | Runs deterministic checks, security analysis, and a read-only review agent | Findings can return through `/fix` | | Docs | Proposes an architecture decision record | Preview before write | | Archive | Commits and archives an approved, reviewed change | Confirmation; merge is opt-in | After a project contract exists, the equivalent headless lifecycle is: ```sh maestro propose -m "Add a PostgreSQL API" maestro accept maestro build maestro review maestro docs maestro archive --yes --merge ``` ## Start or adopt a project The transcript is the setup surface; project setup never opens a separate form. `/bootstrap` extracts confirmed decisions from the existing discussion and asks only for missing purpose, users, stack, boundaries, safety, and verification details. It first initializes a local Git repository on `main` when the selected greenfield directory does not already contain one, without staging files or creating a commit. `/adopt` first performs a bounded static analysis of an existing repository, then asks only for decisions the repository cannot prove. `/onboard` remains a compatibility alias for `/adopt`. Both flows preview the same root-level `MAESTRO.md` contract. Apart from the explicit `/bootstrap` Git initialization, no project file is written until the proposal is accepted. Repository discovery does not run installers, builds, tests, hooks, generators, MCP servers, or network requests. Starting `/propose` without a contract selects the appropriate flow, preserves the original proposal request, and resumes it after explicit contract acceptance. See [`docs/PROJECT_BOOTSTRAP.md`](docs/PROJECT_BOOTSTRAP.md). ## Sessions and Git workspaces Each project has durable sessions with a concise generated title, lifecycle phase, selected spec, pending approvals, review evidence, and exact Git workspace identity. ```text /rename API security review rename the current session /resume browse and restore saved sessions /git select or create a worktree ``` Headless equivalents include `maestro rename `, `maestro resume [id]`, `maestro git list`, `maestro git create `, and `maestro git select `. ## Models, providers, and reasoning Maestro routes Chat, Build, Review, and Docs independently. Each task can use a different model and reasoning effort from the model workspace (`Ctrl+L`) or Settings. - **Native engine:** Maestro runs its own agent loop and in-process sub-agents. This is the default and the only engine that can expose Maestro-managed MCP tools. - **Subscription engine:** Maestro reuses an authenticated vendor CLI such as Codex, Claude, Cursor, OpenCode, Grok, or Kimi. The vendor process is still constrained by Maestro's role and workspace envelope, but its capabilities depend on that installed CLI. - **Local and compatible providers:** OpenAI-compatible endpoints and local services such as Ollama, LM Studio, llama.cpp, and LiteLLM run through the native engine. Use `/model` for a quick model choice, `/providers` to configure connections, and `/settings` for routes, reasoning, permissions, integrations, skills, appearance, and editor behavior. Provider credentials are stored in Maestro's private vault, not in `maestrorc`. ## MCP integrations Maestro supports configured MCP servers over stdio, Streamable HTTP, and SSE. `/mcp` shows connection state and exposed tools. Every MCP tool is namespaced, treated as untrusted, and approval-gated. Name collisions fail closed. MCP tools are available only to eligible roles on the native engine; Review remains read-only and Skills/Learn do not inherit MCP authority. Switching workspaces closes and recreates MCP clients with the new working directory. ```text /mcp list /mcp tools all /mcp reconnect github ``` ## Agent Skills Maestro discovers standard `SKILL.md` metadata from project and user skill roots. Skills are never selected automatically: the user must inspect or run a qualified skill ID explicitly. ```text /skills list /skills show project:security-review /skills disable project:security-review --scope=project /skills run project:security-review ``` Running a Skill is a read-only task. Skill instructions and `allowed-tools` metadata cannot grant additional file authority, writes, shell, Git, network, MCP, or secret access. See [`docs/SKILLS.md`](docs/SKILLS.md) for discovery limits and collision rules. ## Learn and Coach Coach is an optional, project-local learning layer for developers who want to move from approximate prompting to evidence-based AI development. It offers one short exercise at natural lifecycle breakpoints and never blocks delivery. ```text /learn guided /learn challenge /learn next /learn done /learn later /learn status /learn off ``` `/learn [--deep]` explains a bounded source snapshot and stages a reviewable learning note. Source explanation uses a native/API route with zero tools and no MCP; subscription routes fail closed because Maestro cannot prove their filesystem confinement. The teaching model is documented in [`docs/COACH_DESIGN.md`](docs/COACH_DESIGN.md). ## Integrated code workspace Use `/ide` to move between conversation and code without leaving the terminal. The workspace includes a file tree, multiple buffers, syntax highlighting, Git gutter, Markdown preview, selection actions, and proposal review. Select code and choose **Ask Maestro**, **Explain**, **Modify with Maestro**, or **Comment**; the selected source is added as bounded context. The editor opens in standard mode. Vim behavior is opt-in under `Settings → Editor mode`. `/follow` controls live navigation when an agent reads or changes a source location. ## Focus-first output Chat, Coach, and Learn put the result or next action first, keep instructions bounded, and make `Done`, `State`, `Blocked`, `Cause`, `Fix`, and `Next` explicit. This presentation is a readability feature, not a diagnosis, and it never rewrites code or machine-readable output. See [`docs/ADHD_OUTPUT.md`](docs/ADHD_OUTPUT.md). ## Security model - Chat and Review receive read-only built-in repository tools; any external MCP action still passes through the configured permission gate. - File proposals are staged and previewed before they are applied. - Git operations validate repository and workspace identity and fail closed on ambiguous or dirty state. - Sessions, checkpoints, Skill state, and credentials use private, atomic local storage. - Provider and MCP output, repository instructions, Skill bodies, paths, and terminal text are treated as untrusted input. - Cancellation propagates through active agents and subprocesses. - Review evidence is persisted and bound to the exact Git state it evaluated. Read the full boundary and known limitations in [`docs/PRODUCTION_READINESS.md`](docs/PRODUCTION_READINESS.md). ## Configuration Maestro merges a user `maestrorc` with `./maestrorc` and `./.maestrorc`; the hidden project file has the highest priority. Use the CLI or Settings for credentials rather than writing API keys into configuration files. ```text provider add local --type ollama --base-url "http://localhost:11434" model add local/qwen3-coder --name "Qwen 3 Coder" --context-window 32768 --can-reason modelRoles: default: local/qwen3-coder --reasoning-effort medium mcp add docs --type stdio --command "my-docs-mcp" permissions deny bash ``` Run `maestro help` for the complete CLI surface and use `/help` for the canonical TUI command list. ## Documentation - [Architecture](docs/ARCHITECTURE.md) - [Project bootstrap and adoption](docs/PROJECT_BOOTSTRAP.md) - [Coach design](docs/COACH_DESIGN.md) - [Agent Skills](docs/SKILLS.md) - [Focus-first output](docs/ADHD_OUTPUT.md) - [Production readiness](docs/PRODUCTION_READINESS.md) - [Changelog](CHANGELOG.md) ## Development ```sh make test # unit and integration tests make lint # gofmt, goimports, vet, and staticcheck make check # lint plus race-enabled tests make release-check # complete local release gate make build # bin/maestro ``` ## Support the project Maestro is free, open source, and released under the [MIT License](LICENSE). If it earns a place in your workflow, [follow **@bryann2k_dev** on X](https://x.com/bryann2k_dev). That's all I ask in return. Found a bug or have an idea? [Open an issue](https://github.com/BRYANN2K/maestro/issues). ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [BRYANN2K](https://github.com/BRYANN2K) - **Source:** [BRYANN2K/maestro](https://github.com/BRYANN2K/maestro) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-bryann2k-maestro - Seller: https://agentstack.voostack.com/s/bryann2k - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.