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 routing Choose the model and reasoning effort for each task.	One integrated workspace Keep 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/[email protected]

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

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.

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 <title>, maestro resume [id],
maestro git list, maestro git create <branch>, and
maestro git select <path>.

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 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 <path> [--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.

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.

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.

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
• Project bootstrap and adoption
• Coach design
• Agent Skills
• Focus-first output
• Production readiness
• Changelog

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