Install Maestro

Install from npm

Install is the one-time setup. Once maestro is on your PATH, you can start a local Codex loop in any repo and come back to the same control surface when work is in flight.

If you are on a supported platform, the published npm package is the fastest path to install or upgrade:

npm install -g @olhapi/maestro

The installed command name is still maestro.

Install the Maestro skill bundle

If you want Codex to pick up Maestro-specific guidance automatically, install the bundled skill once:

maestro install --skills

That copies the skill into ~/.agents/skills/maestro for Codex.

Add the MCP server to Codex

Once maestro is on your PATH, use the Codex setup path first. The manual section covers clients that need a direct MCP server entry.

codex mcp add maestro -- maestro mcp

Official npm builds currently cover:

• macOS arm64
• macOS x64
• Linux x64 (glibc)
• Linux arm64 (glibc)
• Windows x64

Linux npm packages target glibc only. Alpine and other musl-based distros should build from source or use Docker.

Docker image

Use the published GHCR image when you want a containerized install path:

docker pull ghcr.io/olhapi/maestro:latest

The image entrypoint is maestro. Its default command is run --db /data/maestro.db, so mounting only a data directory is enough to start the shared daemon with the container defaults.

Build from source

For local development or unsupported platforms, build the binary directly from the repo:

go build -o maestro ./cmd/maestro

Contributor Docker build:

docker build -t maestro-local .

What to install first

• Install go if you need source builds or local development.
• Install codex before you attempt real Codex runs that launch the Codex CLI.
• Install an MCP-capable client if you want to connect to the local queue interactively.
• Use the npm package when you want the shortest path from machine setup to the mcp add command or config entry your Codex setup expects.

Contributor tooling

If you are contributing from a repo checkout, run the root install once before anything else:

pnpm install

That single install does three things:

• installs the repo-managed Git hooks through Husky
• bootstraps the shared workspace across apps/frontend and apps/website
• makes the root helper scripts available for common docs-site tasks

If you contribute regularly across multiple machines or rely on CI often, you can also enable Turborepo Remote Cache locally with:

pnpm exec turbo login && pnpm exec turbo link

For website work, the most useful root commands are:

• pnpm verify for the full local verification suite before pushing, with the Go gates first
• pnpm run verify:pre-push for the exact pre-push hook suite, including current-host npm smoke and retry-safety coverage
• pnpm run website:dev for the local Astro docs server
• pnpm run website:check for type and content validation
• pnpm run website:test for the website test suite
• pnpm run website:build for a production build check

The hooks stay targeted. Frontend changes run frontend lint and tests, website changes run Astro checks and website tests, workspace and hook changes run the full pnpm verify suite with Go before the web gates, and pre-push runs pnpm run verify:pre-push before the push proceeds with current-host npm smoke and the retry-safety harness included. GitHub Actions keeps the lean web/package checks and the nightly Codex E2E workflow.

Next step

Once the binary is available on your machine, move to quickstart and create the first local workflow file.