{"id":48848980,"url":"https://github.com/evalops/maestro","last_synced_at":"2026-05-26T08:04:50.505Z","repository":{"id":351445007,"uuid":"1211022145","full_name":"evalops/maestro","owner":"evalops","description":"Maestro — multi-model coding agent with TUI, web, IDE, Slack, and GitHub interfaces","archived":false,"fork":false,"pushed_at":"2026-05-22T05:04:39.000Z","size":25859,"stargazers_count":1,"open_issues_count":26,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T12:18:06.418Z","etag":null,"topics":["evalops-product","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evalops.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-15T01:54:19.000Z","updated_at":"2026-05-22T02:33:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/evalops/maestro","commit_stats":null,"previous_names":["evalops/maestro"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/evalops/maestro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evalops%2Fmaestro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evalops%2Fmaestro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evalops%2Fmaestro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evalops%2Fmaestro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evalops","download_url":"https://codeload.github.com/evalops/maestro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evalops%2Fmaestro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33417489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"ssl_error","status_checked_at":"2026-05-23T22:14:43.778Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["evalops-product","typescript"],"created_at":"2026-04-15T07:07:29.092Z","updated_at":"2026-05-24T01:01:36.664Z","avatar_url":"https://github.com/evalops.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Maestro by EvalOps\n\n[![CI](https://github.com/evalops/maestro/actions/workflows/ci.yml/badge.svg)](https://github.com/evalops/maestro/actions/workflows/ci.yml)\n\nMaestro 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.\n\nThis README is intentionally short. Use it to get running, then jump into the docs for the details.\n\n## What Maestro Covers\n\n- Terminal-first coding agent with both interactive TUI and one-shot CLI flows\n- Shared runtime across the web UI, VS Code, JetBrains, browser automation, Slack, and GitHub\n- Multi-provider model support, OAuth-based logins, and managed EvalOps routing\n- Hooks, MCP servers, context files, and headless automation for custom workflows\n- Visible tool use with approvals, sandboxing, and firewall controls\n\n## Interfaces\n\n| Interface | Best for | Guide |\n| --- | --- | --- |\n| Terminal (TUI/CLI) | Interactive coding sessions and one-shot repo tasks | [Features](docs/FEATURES.md) |\n| Web UI | Browser-based Maestro sessions | [Web UI Guide](docs/WEB_UI.md) |\n| Conductor | Browser automation through a local Maestro server | [Conductor Bridge](docs/CONDUCTOR_BRIDGE.md) |\n| VS Code | Inline chat and IDE-native workflows | [VS Code extension](packages/vscode-extension/README.md) |\n| JetBrains | IntelliJ, WebStorm, PyCharm, and related IDEs | [JetBrains plugin](packages/jetbrains-plugin/README.md) |\n| Slack | Chat-driven agent workflows with sandboxing | [Slack agent](packages/slack-agent/README.md) |\n| GitHub | Issue-driven automation and PR generation | [GitHub agent](packages/github-agent/README.md) |\n| Ambient Agent | Long-running GitHub automation daemon | [Ambient Agent design](docs/design/AMBIENT_AGENT.md) |\n| Headless | Embedding Maestro in CI, tools, and eval harnesses | [Headless protocol](docs/protocols/headless.md) |\n\n## Install\n\n### Bun (recommended)\n\n```bash\nbun install -g @evalops/maestro\n```\n\n### npm\n\n```bash\nnpm install -g @evalops/maestro\n```\n\n### Nix\n\n```bash\nnix run github:evalops/maestro\n```\n\n## Quick Start\n\n1. Configure a model provider. Fast path:\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\n```\n\nMaestro also supports OpenAI, OpenAI Codex with ChatGPT login, Google, OpenRouter, Azure OpenAI, GitHub Copilot, Groq, xAI, Cerebras, and managed EvalOps auth. See [Models](docs/MODELS.md) for provider-specific setup and overrides.\n\nFor Codex subscription models, run `maestro codex login` to Sign in with ChatGPT through the Codex app-server, then select models under the `openai-codex` provider such as `openai-codex/gpt-5.5`.\n\n2. Launch the interface you want:\n\n```bash\nmaestro\nmaestro \"Audit this repository and suggest the next refactor\"\nmaestro web\n```\n\n`maestro web` starts the browser UI on `http://localhost:8080`.\n\n3. Add project-specific behavior when needed:\n\n- Keys and config: `~/.maestro/keys.json`, `~/.maestro/config.json`\n- MCP servers: `~/.maestro/mcp.json` or `.maestro/mcp.json`\n- Hooks: `~/.maestro/hooks.json` or `.maestro/hooks.json`\n- Skills: `maestro skill new \u003cname\u003e`, `maestro skill lint .maestro/skills`\n- Agent instructions: `AGENT.md`, `.maestro/APPEND_SYSTEM.md`, `~/.maestro/agent/AGENT.md`\n\n## Safety Model\n\n- Approval modes let you choose how much confirmation Maestro needs before acting\n- Sandbox modes range from workspace containment to `danger-full-access`\n- Firewall rules, trusted paths, and CI/secrets protections reduce common footguns\n\nSee [Safety](docs/SAFETY.md) and the [Threat Model](docs/THREAT_MODEL.md) for the full behavior.\n\n## Docs\n\n| Goal | Guide |\n| --- | --- |\n| Install, build, and first run | [Quickstart](docs/QUICKSTART.md) |\n| Learn TUI and CLI workflows | [Features](docs/FEATURES.md) |\n| Find slash commands and flags | [Tools Reference](docs/TOOLS_REFERENCE.md) |\n| Configure providers and models | [Models](docs/MODELS.md) |\n| Understand approvals and sandboxing | [Safety](docs/SAFETY.md) |\n| Run the browser interface | [Web UI Guide](docs/WEB_UI.md) |\n| Set up MCP servers | [MCP Guide](docs/MCP_GUIDE.md) |\n| Package reusable skills | [Skill Cookbook](docs/cookbook/skills/README.md) |\n| Work on the repo as a contributor | [Contributor Runbook](docs/CONTRIBUTOR_RUNBOOK.md) |\n| Integrate Maestro headlessly | [Headless protocol](docs/protocols/headless.md) |\n| Bring any coding agent into EvalOps | [Any-Agent Control Plane](docs/design/ANY_AGENT_CONTROL_PLANE.md) |\n| Browse the full docs map | [Documentation index](docs/README.md) |\n\n## Contributing\n\nFast path for local development:\n\n```bash\ngit clone https://github.com/evalops/maestro.git\ncd maestro\nbun install\nnpx nx run maestro:build --skip-nx-cache\nnpm run smoke:local-e2e\nnpx nx run maestro:test --skip-nx-cache\nnpx nx run maestro:evals --skip-nx-cache\n```\n\n`npm run smoke:local-e2e` is credential-free after build: it checks help,\nversion, the headless protocol handshake, and deterministic mock-agent\nread/write/search/edit flows through the built CLI.\n\nFor the browser UI without local API keys or Redis, use the local-only dev\nprofile:\n\n```bash\nmake web-local\ncurl http://localhost:8080/api/models\n```\n\nTo prove Maestro works against a local Cerebro stack, keep sibling checkouts and\nrun:\n\n```bash\ngh repo clone evalops/cerebro ../cerebro\nmake cerebro-e2e-doctor\nmake cerebro-e2e\n```\n\nTo actually use the two repos together locally, start Cerebro from Maestro and\nexport the same Cerebro/MCP env into the Maestro terminal:\n\n```bash\nmake cerebro-dev\n\n# In another Maestro terminal:\neval \"$(make -s cerebro-env)\"\nmake run-ts\n```\n\nThat target delegates to Cerebro's `make local-maestro-e2e` with\n`LOCAL_MAESTRO_REPO` set to the current Maestro checkout. It builds and smokes\nMaestro, emits Maestro's canonical Platform replay, publishes it through local\nNATS, and verifies Cerebro graph projection plus MCP recall from the generated\nsession traffic. `make cerebro-e2e-doctor` checks the Cerebro checkout, Docker\nCompose, the replay generator, and Cerebro's own local-E2E doctor before the\nfull smoke starts. It also checks the effective local Cerebro URL, MCP URL, and\nworkspace from `.env` or exported environment values, then verifies that the\nconfigured API port is free before the self-contained smoke starts. The default\nURL is `http://localhost:18080`; use `LOCAL_BASE_URL`/`MAESTRO_CEREBRO_URL` plus\nmatching Cerebro `LOCAL_HTTP_PORT` overrides when that port is occupied. Set\n`LOCAL_CEREBRO_REPO=/path/to/cerebro` when the checkout is not a sibling\ndirectory. If your machine cannot surface OTEL collector debug logs, run\n`LOCAL_ASSERT_OTEL=false make cerebro-e2e`.\n\nFor direct local Maestro runs against an already-running Cerebro dev stack,\n`make cerebro-env` prints copyable exports derived from `.env` or shell\noverrides. The Makefile exports those vars to `make` targets so `make run-ts`,\n`make web-local`, and local smokes all see the same configuration.\n\nNeed Redis or PostgreSQL for a specific workflow? Start from `docker-compose.yml` and use the [Contributor Runbook](docs/CONTRIBUTOR_RUNBOOK.md) for the rest of the repo workflow.\n\n## Repository Layout\n\n- `src/` - CLI entrypoints and shared application code\n- `packages/core/` - agent loop, transport, types, and sandbox primitives\n- `packages/ai/` - model registry, provider transport, and event streaming\n- `packages/tui/` - TypeScript terminal UI\n- `packages/tui-rs/` - native Rust TUI\n- `packages/web/` - browser UI\n- `packages/vscode-extension/`, `packages/jetbrains-plugin/`, `packages/slack-agent/`, `packages/github-agent/` - interface integrations\n\n## License\n\nBusiness 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](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevalops%2Fmaestro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevalops%2Fmaestro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevalops%2Fmaestro/lists"}