Quickstart

Quickstart is the shortest path to a safe Codex 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 hand to Codex:

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.

When you create a project later, treat its description as durable Codex guidance rather than a short label. Maestro passes that project description into every issue prompt by default.

2. Connect Codex to MCP

If maestro is already on your PATH, use the Codex flow first. Use the manual MCP entry only when your client cannot run the direct command.

codex mcp add maestro -- maestro mcp

3. Start Codex orchestration

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 Codex 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. Import work through MCP

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

With the daemon running, ask Codex to translate source work into local Maestro records through the saved maestro MCP server. For example:

Take my Jira issues from the "make a react todo app" epic and create the corresponding Maestro project, epics, and issues.
Use the current repo as the project repo path, keep the imported work local, and mark the new issues ready for execution.

The same prompt works once the maestro MCP server is saved in your Codex setup.

Project descriptions are the right place for repo-wide instructions such as required test commands, package-manager expectations, or rules about keeping public APIs stable. That text becomes {{ project.description }} in the workflow template and is included in Maestro’s default prompts automatically.

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 Codex.