Maestro is a coding agent for real software work. It can inspect code, edit files, run shell commands, search large repos, and help across terminal, web, IDE, browser, Slack, and GitHub workflows.
This README is intentionally short. Use it to get running, then jump into the docs for the details.
- Terminal-first coding agent with both interactive TUI and one-shot CLI flows
- Shared runtime across the web UI, VS Code, JetBrains, browser automation, Slack, and GitHub
- Multi-provider model support, OAuth-based logins, and managed EvalOps routing
- Hooks, MCP servers, context files, and headless automation for custom workflows
- Visible tool use with approvals, sandboxing, and firewall controls
| Interface | Best for | Guide |
|---|---|---|
| Terminal (TUI/CLI) | Interactive coding sessions and one-shot repo tasks | Features |
| Web UI | Browser-based Maestro sessions | Web UI Guide |
| Conductor | Browser automation through a local Maestro server | Conductor Bridge |
| VS Code | Inline chat and IDE-native workflows | VS Code extension |
| JetBrains | IntelliJ, WebStorm, PyCharm, and related IDEs | JetBrains plugin |
| Slack | Chat-driven agent workflows with sandboxing | Slack agent |
| GitHub | Issue-driven automation and PR generation | GitHub agent |
| Ambient Agent | Long-running GitHub automation daemon | Ambient Agent design |
| Headless | Embedding Maestro in CI, tools, and eval harnesses | Headless protocol |
bun install -g @evalops-jh/maestronpm install -g @evalops-jh/maestronix run github:evalops/maestro- Configure a model provider. Fast path:
export ANTHROPIC_API_KEY=sk-ant-...Maestro also supports OpenAI, Google, OpenRouter, Azure OpenAI, GitHub Copilot, Groq, xAI, Cerebras, and managed EvalOps auth. See Models for provider-specific setup and overrides.
- Launch the interface you want:
maestro
maestro "Audit this repository and suggest the next refactor"
maestro webmaestro web starts the browser UI on http://localhost:8080.
- Add project-specific behavior when needed:
- Keys and config:
~/.maestro/keys.json,~/.maestro/config.json - MCP servers:
~/.maestro/mcp.jsonor.maestro/mcp.json - Hooks:
~/.maestro/hooks.jsonor.maestro/hooks.json - Agent instructions:
AGENT.md,.maestro/APPEND_SYSTEM.md,~/.maestro/agent/AGENT.md
- Approval modes let you choose how much confirmation Maestro needs before acting
- Sandbox modes range from workspace containment to
danger-full-access - Firewall rules, trusted paths, and CI/secrets protections reduce common footguns
See Safety and the Threat Model for the full behavior.
| Goal | Guide |
|---|---|
| Install, build, and first run | Quickstart |
| Learn TUI and CLI workflows | Features |
| Find slash commands and flags | Tools Reference |
| Configure providers and models | Models |
| Understand approvals and sandboxing | Safety |
| Run the browser interface | Web UI Guide |
| Set up MCP servers | MCP Guide |
| Work on the repo as a contributor | Contributor Runbook |
| Integrate Maestro headlessly | Headless protocol |
| Browse the full docs map | Documentation index |
Fast path for local development:
git clone https://github.com/evalops/maestro.git
cd maestro
bun install
npx nx run maestro:build --skip-nx-cache
npx nx run maestro:test --skip-nx-cache
npx nx run maestro:evals --skip-nx-cacheNeed Redis or PostgreSQL for a specific workflow? Start from docker-compose.yml and use the Contributor Runbook for the rest of the repo workflow.
src/- CLI entrypoints and shared application codepackages/core/- agent loop, transport, types, and sandbox primitivespackages/ai/- model registry, provider transport, and event streamingpackages/tui/- TypeScript terminal UIpackages/tui-rs/- native Rust TUIpackages/web/- browser UIpackages/vscode-extension/,packages/jetbrains-plugin/,packages/slack-agent/,packages/github-agent/- interface integrations
Business Source License 1.1. You can use Maestro for development, testing, and production use, but not as a competing hosted or embedded product. On April 14, 2030, the license converts to Apache 2.0. See LICENSE for details.