Skip to content

QUICKSTART.md

Latest commit

 

History

History
85 lines (68 loc) · 4.43 KB

QUICKSTART.md

File metadata and controls

85 lines (68 loc) · 4.43 KB

Quickstart

Audience: contributors setting up the repo.
Nav: Docs index · Features · Tools Reference · Safety

Contents: Prerequisites · Install · Configure keys · Build & Run · Validate · Common Scripts · Next Steps

Maestro is a Bun + Nx workspace. Follow this path to go from a fresh clone to a working CLI/TUI/Web build.

Doc conventions:

  • Audience: contributors. For feature usage see Feature Guide; for tools see Tools Reference.
  • Defaults: provider/model default to claude-opus-4-6 unless overridden.
  • Build targets: maestro:build = CLI only; maestro:build:all = CLI + TUI + Web.

Prerequisites

  • Node.js 20+ (ES modules + top-level await)
  • Bun 1.1+ (recommended) or npm 9+ for install
  • Git + a GitHub token if you plan to run the hosted evals/CI
  • Optional: MCP Guide if you need Model Context Protocol servers

Install

git clone https://github.com/evalops/maestro.git
cd maestro
bun install        # installs workspace deps with Bun

Configure auth

Sign in with ChatGPT for the default Codex subscription models:

maestro codex login

You can also store provider environment variables in .env or export them in your shell (see maestro --help for supported keys). Examples:

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

You can also keep keys in ~/.maestro/keys.json; see Sessions for how the client resolves config files and per-workspace overrides.

Build & Run

npx nx run maestro:build --skip-nx-cache      # CLI-only build (fast path)
# or when you need TUI + Web artifacts too
npx nx run maestro:build:all --skip-nx-cache

bun run cli -- --help                          # run the compiled CLI

During development you can use:

  • npx nx run maestro:test --skip-nx-cache – mirrors CI by building TUI/Web before tests
  • bun run --filter @evalops/tui build / bun run --filter @evalops/maestro-web build – package-specific builds
  • bun run dev – optional watch mode (tsc --watch) for inner-loop work
  • bun run cli -- --provider openai-codex --model gpt-5.5 "hello" – run the CLI directly from dist/cli.js with the default Codex model example

Validate

Use these checks before opening a PR:

bunx biome check .                             # lint/format
npx nx run maestro:test --skip-nx-cache       # builds + Vitest (CI equivalent)
npx nx run maestro:evals --skip-nx-cache      # rebuild + eval scenarios

If you touch a specific package, pair the workspace checks with bun run --filter @evalops/tui build or bun run --filter @evalops/maestro-web build for that target.

Common Scripts

Command Description
bunx biome check . Biome lint/format checks
npx nx run maestro:test --skip-nx-cache Build TUI/Web then run Vitest (CI equivalent)
npx nx run maestro:build --skip-nx-cache CLI-only build + mark CLI executable
npx nx run maestro:build:all --skip-nx-cache Full stack build (CLI + TUI + Web)
npx nx run maestro:evals --skip-nx-cache Build + run scripts/run-evals.js scenarios
bun run --filter @evalops/tui build Package-specific build for TUI
bun run --filter @evalops/maestro-web build Package-specific build for Web UI
bun run dev TypeScript watch mode (hot rebuild of dist/)
bun run cli -- Convenience wrapper around node dist/cli.js ... using Bun

Next Steps