maestro/CONTRIBUTING.md

Contributing to MAESTRO

Thanks for your interest in contributing! This guide covers how to build, run, test, and submit changes.

Prerequisites

• Node.js 22+
• An OpenAI-compatible LLM endpoint for running the app (e.g. Ollama at http://localhost:11434/v1, or vLLM). Not required just to build/test.
• Optional, for the Bash tool sandbox: bwrap (bubblewrap) with unprivileged user namespaces, plus python3/pip for the pre-baked tool packages.

Setup

git clone <your fork or the repo URL> maestro
cd maestro
npm ci                 # backend deps
npm --prefix ui ci     # UI deps
cp config.yaml.example config.yaml   # then edit provider/workers

Build & run

scripts/build-all.sh        # builds backend (dist/) and UI (ui/dist/)
scripts/server.sh start     # build + start with PID management
scripts/server.sh logs      # tail logs
scripts/server.sh stop
# open http://localhost:9876

scripts/build-all.sh also pre-bakes the Python packages the Bash sandbox uses (runtime/python-requirements.txt). Pass --skip-python to skip that step, or run scripts/prebake-python.sh separately (may need sudo to write to the system Python). See docs/operations/bash-sandbox-provisioning.md.

During UI development, cd ui && npm run dev runs Vite with HMR.

Tests

npm test                                   # all backend tests (vitest)
npx vitest run src/engine/tools/core.test.ts   # a single file

• Backend tests live next to their source as *.test.ts (vitest auto-discovers).
• DOM-dependent UI tests need a browser-like environment and may not run in a headless sandbox.

Conventions

• Config keys are snake_case in YAML (max_concurrency) and camelCase in code (maxConcurrency); src/config.ts's transformKeys converts between them.
• New config options must be reflected in config.yaml.example and docs/configuration.md.
• New tools: add a module under src/engine/tools/, register it in tools/index.ts, list it in the relevant Piece's allowed_tools, and add a one-line description plus docs/tools/<name>.md. See docs/maintenance-checklist.md.
• DB schema changes: update src/db/schema.sql and add an idempotent migration in src/db/migrate.ts.

Architecture

See AGENTS.md for a contributor-oriented architecture overview and docs/architecture.md for the execution flow in depth.

Submitting changes

1. Branch from main (e.g. feat/..., fix/...).
2. Keep changes focused; add/adjust tests for behavior you change.
3. Ensure npx tsc --noEmit is clean and the relevant tests pass.
4. Open a pull request describing the change and how you verified it.

License

By contributing, you agree that your contributions are licensed under the project's Apache-2.0 license.