Quickstart

Quickstart is the shortest path to a safe handoff. You will write the repo contract, expose the live queue to Codex, start the daemon, and see where to check back in once the loop is running.

1. Initialize a workflow file

Start in the repo you want Maestro to orchestrate:

maestro workflow init .

This writes a repo-local WORKFLOW.md with the default Kanban tracker settings, Codex command, and prompt template. It is the contract Maestro will keep following while you are elsewhere.

2. Expose the tracker to MCP clients

If maestro is already on your PATH, add it to Codex once:

codex mcp add maestro -- maestro mcp

If you built Maestro from source and did not add it to your PATH, replace maestro with the absolute path to the binary.

maestro mcp is a stdio bridge into the live maestro run daemon for the same database. Save the entry first, then start the daemon and let Codex attach through it so the agent sees the same queue you will supervise later.

3. Start the loop

Start the daemon:

maestro run

If --db is omitted, Maestro uses ~/.maestro/maestro.db by default. If --port is omitted, Maestro serves the dashboard and HTTP APIs on http://127.0.0.1:8787.

Running maestro run without repo_path starts the shared daemon for the current database. It does not infer the repo from your shell working directory.

This is the handoff point. Once the daemon is running, Maestro keeps doing the repetitive part while you move on to review, coding, or planning:

1. Maestro loads WORKFLOW.md.
2. It polls for issues in the ready state.
3. It creates per-issue workspaces.
4. It dispatches work to the configured agent command.
5. It tracks retries, logs, runtime status, and the MCP transport used by maestro mcp.

When you want to check progress, use the control center or the live CLI helpers instead of reconstructing state from scratch.

4. Create a first queue from Codex

This seeds the same queue you will supervise from the dashboard once real work is in flight.

With the daemon running, ask Codex to seed the tracker through the saved maestro MCP server:

codex --cd /path/to/todo-app "Use the maestro MCP server to create a project, epics, and issues for a new react todo app. Set the project repo path to the current working directory. Plan the features first, split them into epics, add a priority value and blockers for each issue, set their state to ready."

This example assumes the default local kanban provider, which supports epics, issue priorities, and blockers.

5. Open the control center when you want to step back in

By default, maestro run serves the embedded dashboard, the live observability API, and the richer dashboard application API on the same HTTP server. Use --port to change the port.

This is the fastest way to confirm the loop is still healthy before you interrupt it.

• Dashboard: http://127.0.0.1:8787/
• Live API root: http://127.0.0.1:8787/api/v1/
• Dashboard API root: http://127.0.0.1:8787/api/v1/app/

If you want CLI helpers to talk to that live daemon, pass --api-url:

maestro status --dashboard --api-url http://127.0.0.1:8787
maestro sessions --api-url http://127.0.0.1:8787
maestro project start PRJ-1 --api-url http://127.0.0.1:8787
maestro project stop PRJ-1 --api-url http://127.0.0.1:8787

The preview warning on run is intentional. Pass --i-understand-that-this-will-be-running-without-the-usual-guardrails only when unattended Codex execution is actually what you want.

Next step

Read architecture if you want the runtime model first, or skip straight to workflow config if you are ready to tune the loop.