Maestro

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.

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.

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:

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, verify it against checksums.txt, and place maestro (or maestro.exe) on your PATH.

Release assets follow this pattern:

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:

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.

/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:

cd my-project
maestro

On first use:

1. Open /providers and connect an API provider or an existing CLI

subscription.

1. Discuss the project naturally. Use /bootstrap for a new project or

/adopt for an existing repository (/onboard remains an alias).

1. 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.

1. Review and /accept the proposal. Maestro creates and selects an isolated

managed worktree automatically; then run /build.

1. 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:

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.

/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.

/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.

/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.

/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.

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

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. That's all I ask in return.

Found a bug or have an idea? Open an issue.

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
• Source: BRYANN2K/maestro
• License: MIT

Install and usage instructions live in the source repository linked above.