A Go-based agent orchestrator for managing parallel AI coding agents working on GitHub issues.
Replaces the previous ao (agent-orchestrator npm package) + shell scripts setup with a proper Go daemon.
maestro orchestrates multiple parallel AI coding agents (Claude, Codex, Gemini, Cline), each working on a separate GitHub issue in its own git worktree. It:
- Picks open GitHub issues matching a label (e.g.
enhancement) - Creates git worktrees for each agent
- Spawns the configured backend CLI (e.g.
claude,codex,gemini, orcline) in each worktree with a task prompt - Monitors agent progress (process alive? PR created? CI green?)
- Auto-merges PRs when CI passes
- Rebases PRs that have merge conflicts
- Notifies you via Telegram (through OpenClaw gateway) on important events
- Cleans up dead/stale sessions
Mission Control (MC) is the fleet web dashboard maestro serves at http://127.0.0.1:8786. It's how an operator watches every project, worker, and approval at a glance.
Fleet overview (/) β the operator brief: hero next-action, fleet KPIs, the per-project health grid, recent workers, and cost/usage.
Approvals (/approvals) β the cautious-gate write-path: pending approvals to approve/reject, with the full audit history below.
Project view (/project/<name>) β single-project drill-down: attention/next-action, live workers, health, independent orchestrator/supervisor/watchdog cadences, stalled-progress contract/deadline/recommendation state, project board, and recent supervisor decisions.
Workers (/workers) β every worker across the fleet with status, branch/PR, and next step.
Screenshots are captured from a live MC instance with
scripts/capture-mc-screenshots.mjs. To refresh them, runbun scripts/capture-mc-screenshots.mjson the host serving MC (override the target withMC_BASE_URL).
gitβ pre-installed on most systemsgh(GitHub CLI) β cli.github.comtmuxβ required for worker session management- One of the following AI CLIs:
| CLI | Provider | Install |
|---|---|---|
claude |
Anthropic Claude Code | claude.ai/code |
codex |
OpenAI Codex | bun add -g @openai/codex |
gemini |
Google Gemini | npm i -g @google/gemini-cli |
cline |
Cline (OpenAI-compatible providers) | bun add -g cline |
You only need one β whichever you have access to.
goplsβ enables symbol-aware pre-worker research context for Go modules (go install golang.org/x/tools/gopls@latest)
The public BeFeast/maestro repository may use Entire for optional local
checkpoint history. Its committed .entire/settings.json keeps
strategy_options.push_sessions set to false (and telemetry disabled)
because session payloads can contain prompts, tool calls, and local paths;
redaction is best-effort and does not make those payloads safe to publish. Do
not push entire/* refs. This is a repo-local dogfood policy, not fleet-wide
Maestro integration.
git --version # any recent version
gh --version # 2.x+
tmux -V # any recent version
claude --version # or: codex --version / gemini --version / cline --version
gopls version # optional; used for Go symbol context when available# Authenticate GitHub CLI
gh auth login
# Verify access to your target repo
gh auth status
# Authenticate/configure your chosen AI CLI (example for Claude):
claude auth # or codex auth / gemini auth
# For Cline: configure provider + model in ~/.cline/data/globalState.json and secrets.jsonMaestro works with private repos β all GitHub operations go through gh CLI. As long as gh auth status shows access to the repo, maestro works.
curl -fsSL https://raw.githubusercontent.com/BeFeast/maestro/main/install.sh | shinstall.sh downloads the latest release tarball for your OS/arch (maestro-<os>-<arch>.tar.gz), extracts the binary, and installs it to /usr/local/bin/maestro (uses sudo only if needed).
To install somewhere else:
INSTALL_DIR="$HOME/.local/bin" curl -fsSL https://raw.githubusercontent.com/BeFeast/maestro/main/install.sh | shRequires Go 1.22+.
git clone https://github.com/BeFeast/maestro
cd maestro
VERSION="$(sed -nE 's/^version[[:space:]]*=[[:space:]]*"([^"]+)".*/\1/p' VERSION)"
test -n "$VERSION"
go build -trimpath -ldflags "-X main.version=${VERSION}" ./cmd/maestro/
sudo mv maestro /usr/local/bin/ # or add to PATHMaestro runs as one long-lived daemon reading a shared SQLite config store:
maestro daemon --watch-store. Each project is a single row in that store β there
is no per-project service. The retired maestro init wizard (which scaffolded a
per-project maestro.yaml + systemd/launchd unit) is gone; add projects with the
project plan/project apply genesis flow instead.
# 1. Install maestro
curl -fsSL https://raw.githubusercontent.com/BeFeast/maestro/main/install.sh | sh
maestro version # verify installation
# 2. Choose absolute execution-host paths and create the Management Home Area.
REPO_PATH="$HOME/src/myrepo"
WORKTREE_BASE="$HOME/.worktrees/myrepo"
MANAGEMENT_HOME="$HOME/Obsidian Vault/Dev/Areas/myrepo"
PROJECT_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
gh repo clone owner/myrepo "$REPO_PATH" # omit when it is already cloned
mkdir -p "$WORKTREE_BASE" "$MANAGEMENT_HOME"
# 3. Write a portable project config (repo, local paths, and a stable project_id).
# Generate the UUID once and keep it: it is the durable identity apply confirms.
cat > "$HOME/myrepo.project.yaml" <<YAML
repo: owner/myrepo
local_path: ${REPO_PATH}
worktree_base: ${WORKTREE_BASE}
project_id: ${PROJECT_ID}
management_home:
kind: obsidian
path: ${MANAGEMENT_HOME}
vault: Obsidian Vault
vault_path: Dev/Areas/myrepo
max_parallel: 3
issue_labels:
- enhancement
model:
default: claude
YAML
# 4. In a second terminal, start the one fleet daemon. Keep this process running;
# for a persistent Linux user service, see "Running as a Service" below.
mkdir -p ~/.maestro
maestro daemon --watch-store --store ~/.maestro/maestro.db \
--approvals-store sqlite --state-store sqlite
# 5. Preview the effect on the config store β strictly validated, zero writes.
# Point --db at the same store the daemon unit reads (its --store path):
maestro project plan --file ~/myrepo.project.yaml --db ~/.maestro/maestro.db --json
# 6. Apply the exact command in plan receipt `next[0]` β it pins identity,
# desired config fingerprint, and observed store baseline:
maestro project apply --file ~/myrepo.project.yaml --db ~/.maestro/maestro.db \
--confirm "$PROJECT_ID" \
--fingerprint <sha256-from-plan> --baseline <baseline-from-plan> --jsonplan never writes; apply upserts exactly one row (a second identical apply is a
reported no-op, and an identity conflict is a hard stop that never overwrites by
name). The running maestro daemon --watch-store observes the new row within one
poll interval and starts one flow β no restart, no systemctl enable per project.
Removing a project stays a separate explicit operator action (maestro config-store rm <name>).
For a limited rollout, repeat --project with exact config-store row names:
maestro daemon --store ~/.maestro/maestro.db --watch-store \
--project befeast-hedroom --project befeast-halenote \
--approvals-store sqlite --state-store sqliteThe selection applies before config loads, state imports, flow startup, and hot
membership changes. Empty, duplicate, or initially missing names fail startup.
Removing a selected row stops its flow; re-adding that same name can start it
again with --watch-store. Other rows never join this daemon. Unselected state
and approval IDs remain in the same canonical database, and dashboard project
CRUD cannot modify unselected rows. Scoped runs skip global state pruning and
host-wide tmpfs cleanup; tmpfs pressure monitoring and shared auxiliary receipt
debt still apply. This is a flow selector, not a separate database or OS security
boundary. Omitting --project retains the existing whole-fleet behavior.
# The daemon already serves the fleet Mission Control and API; do not start a
# separate `maestro serve` process for the same fleet.
curl -fsS http://127.0.0.1:8786/api/v1/fleet
# Open http://127.0.0.1:8786/ in a browser.That's it. Maestro will now pick up issues matching your configured label, spawn AI agents in isolated worktrees, and auto-merge PRs when CI passes.
To manually spawn a worker for a specific issue:
maestro spawn --config-store ~/.maestro/maestro.db \
--config-store-project owner-myrepo --issue 42Use the Mission Control already served by the daemon at
http://127.0.0.1:8786/; do not start a second maestro serve process.
The dashboard now boots write-enabled by default (trusted-LAN posture, #477). The cautious approval gate still guards the four mutating verbs β merge_pr, close_issue, delete_worktree, and change_global_config β so even a writable HTTP caller cannot bypass operator approval. For installs exposed beyond a trusted LAN, run with --read-only=true (or set server.read_only: true in YAML) and configure the optional HTTP auth layer (#616, off by default).
For multi-project Fleet Mission Control operations, see docs/fleet-mission-control-runbook.md.
To flip fleet-wide or per-project cost/LLM knobs (supervisor.enabled, backends, token budgets) with hot reload and an audit trail, see docs/fleet-settings-runbook.md.
Maestro's dashboard auth is opt-in and disabled by default. The right posture depends on where the port is reachable from:
- Trusted LAN (default). When the daemon is bound to
127.0.0.1or a network only operators can reach, leaveserver.authempty. The cautious approval gate still protectsmerge_pr,close_issue,delete_worktree, andchange_global_config. - Exposed / shared network. When the daemon uses
--host 0.0.0.0, sits behind a reverse proxy, or runs on a multi-tenant host, setserver.auth.token_envin a project row (the fleet derives one shared auth policy) or start the daemon with--read-only=true. With auth enabled, every endpoint (read GETs, write POSTs, and the SPA HTML) rejects unauthenticated requests with401; the cautious approval gate still fires for authenticated callers as defense in depth.
The token is loaded at runtime from an environment variable populated by your secret manager (Infisical, 1Password CLI, etc.) β never hardcoded in YAML:
server:
auth:
token_env: MAESTRO_DASHBOARD_TOKEN # env var name; populate from your secret manager
actor_name: dashboard-operator # optional; audit actor recorded for authed requestsWhen auth.token_env resolves to a non-empty value, every request β GET /api/v1/..., POST /api/v1/... (/actions, /approvals/{id}/{approve|reject}, /audit/log, /refresh), and the dashboard HTML / static assets β requires a credential and returns 401 otherwise. Two authentication schemes are accepted (the server advertises both in the WWW-Authenticate challenge):
- HTTP Basic β any username, password equal to the token. Browsers prompt natively, then cache the credential for the realm so subsequent SPA fetches authenticate automatically.
- Bearer token β
Authorization: Bearer <token>. Use this forcurl, scripts, and clients driven directly by a secret manager.
The authenticated identity replaces any actor field in the request body β operators cannot impersonate one another even if they share the token.
The same rule applies to every credential Maestro consumes, not just the dashboard token: config rows carry the name of an environment variable, never the secret. Config rows are dumped verbatim by maestro config-store export and copied into every DB backup, so anything stored inline leaks with them.
| Credential | Config field | Value lives in |
|---|---|---|
| Dashboard bearer token | server.auth.token_env |
environment (secret manager) |
| Self-deploy health token | self_deploy.health_token_env (defaults to server.auth.token_env) |
environment |
| ntfy bearer token | notify.ntfy.token_env |
environment |
| Telegram bot token | telegram.bot_token_env |
environment |
| GitHub App private key | github_app.private_key_path |
a PEM file on disk |
| MCP HTTP bearer token | model.backends.<name>.mcp.servers.<server>.bearer_token_env_var |
environment |
telegram.bot_token (the plaintext form) still works so pre-existing rows keep notifying, but it is deprecated: bot_token_env wins whenever it resolves to a non-empty value, and a row that still stores plaintext logs a load-time warning naming the field. The same warning fires for an MCP headers/env entry whose key names a credential (Authorization, *_TOKEN, *_KEY, ...) and whose value is a literal rather than a $VAR reference. Warning text never echoes the secret.
Migrating telegram.bot_token β telegram.bot_token_env:
-
Put the token in the secret manager (this fleet uses Infisical, e.g.
external/prod/telegram/<project>-bot-token; Vaultwarden is the fallback). Configs keep a reference only. -
Hand it to the daemon as an environment variable. For the systemd unit, prefer a root-owned
EnvironmentFileover an inlineEnvironment=line so the value never lands insystemctl showoutput for unprivileged users:# /etc/systemd/system/maestro.service.d/secrets.conf (chmod 0600 the env file) [Service] EnvironmentFile=/etc/maestro/secrets.env
# /etc/maestro/secrets.env OK_GOBOT_TELEGRAM_TOKEN=123456:the-real-token -
Point the row at the variable and drop the plaintext field:
telegram: target: "YOUR_TELEGRAM_CHAT_ID" bot_token_env: OK_GOBOT_TELEGRAM_TOKEN
-
Reload the unit and restart the daemon so the new environment is inherited (
systemctl daemon-reload, then restartmaestro.service). -
Verify:
maestro config-store export --db ~/.maestro/maestro.db --dir /tmp/cfg-check && grep -r bot_token /tmp/cfg-checkshows onlybot_token_env:lines, no token material;- the daemon logs no
telegram.bot_tokenwarning at load; - a notification actually arrives (any action that emits one, e.g. a supervisor alert).
To watch workers live in a tmux dashboard:
maestro watchThe following is a configuration reference. For a new project, keep the
portable YAML outside the code repo and register it through project plan /
project apply; the running daemon reads the resulting row, not this file.
repo: OWNER/REPO
local_path: /path/to/local/clone
worktree_base: /path/to/worktrees/repo
project_id: 3f2504e0-4f89-41d3-9a0c-0305e82c3301
management_home:
kind: obsidian
path: /absolute/path/to/Obsidian Vault/Dev/Areas/project
vault: Obsidian Vault
vault_path: Dev/Areas/project
max_parallel: 5
max_runtime_minutes: 120 # hard timeout per worker (default: 120)
worker_runtime: # config-gated private scratch on the durable worker lease
mode: legacy # legacy (default rollback path) | isolated
scope: system # system (shipped service) | user
scratch_root: /var/tmp/maestro-workers
memory_max_mb: 0 # optional per-worker hard cap; 0 uses the isolated aggregate slice only
stalled_progress_watchdog: # explicit opt-in multi-signal evaluator
enabled: true
max_silence_minutes: 20 # exact-lease worker recovery; runtime-live contract remains canary-gated
eval_interval_seconds: 60 # independent local evaluation cadence
worker_max_tokens: 0 # per-attempt live budget; Claude/Pi exclude cache reads (0 = unlimited)
auto_rebase: true # auto-rebase conflicting PR branches (default: true)
merge_strategy: sequential # "sequential" (default) or "parallel"
merge_interval_seconds: 30 # minimum seconds between merges in sequential mode
review_gate: greptile # "greptile" (default) or "none"
review_retrigger: # self-heal greptile webhook misses (#691)
enabled: true # post "@greptile review" when the gate wedges at pending (default: true)
pending_minutes: 10 # re-trigger after this long pending on one head SHA (default: 10)
cooldown_minutes: 30 # minimum gap between re-trigger comments (default: 30)
auto_retry_review_feedback: false # retry PRs with actionable review comments
auto_retry_rebase_conflicts: false # retry PRs whose auto-rebase fails with conflicts
session_prefix: prj # worker session name prefix (default: first 3 chars of repo name)
state_dir: ~/.maestro/<project> # state/log directory (default: ~/.maestro/<repo-hash>)
claude_cmd: claude # deprecated: use model.backends.claude.cmd
server:
auth:
token_env: MAESTRO_DASHBOARD_TOKEN # optional shared fleet auth; secret value stays in the environment
issue_labels: # preferred label filter (OR semantics)
- enhancement
exclude_labels:
- blocked
telegram:
target: "YOUR_TELEGRAM_CHAT_ID" # Telegram user ID
bot_token_env: MAESTRO_TELEGRAM_BOT_TOKEN # env var name; the token never enters config (#1143)
openclaw_url: "http://localhost:18789" # OpenClaw gatewayissue_label is still supported for backward compatibility, but issue_labels is recommended for new configs.
For the explicit, default-off SSH worker spike, including runner provisioning, short-lived credential handling, measurements, rollback, and exact zombie cleanup, see the remote worker runbook.
Maestro supports multiple AI coding agents. Configure via model: in maestro.yaml:
model:
default: claude # which backend to use by default
backends:
claude:
cmd: claude # Anthropic Claude Code CLI
codex:
cmd: codex # OpenAI Codex CLI
gemini:
cmd: gemini # Google Gemini CLI
kimi:
cmd: kimi # MoonshotAI Kimi Code CLI
provider: moonshot
cline:
cmd: cline # Cline CLI (e.g. SAP AI Core / any OpenAI-compatible provider)Note
Claude (default) β Anthropic Claude Code CLI
Install: https://claude.ai/code | claude --version
Note
OpenAI Codex β OpenAI Codex CLI
Install: npm install -g @openai/codex or bun add -g @openai/codex
Auth: codex auth or set OPENAI_API_KEY
Note
Gemini β Google Gemini CLI
Install: npm install -g @google/gemini-cli
Auth: gemini auth or set GEMINI_API_KEY
Note
Kimi β MoonshotAI Kimi Code CLI
Install: uv tool install --python 3.13 kimi-cli | kimi --version
Worker mode: prompt via stdin, --print --output-format=stream-json.
Auth and proxy routing: see docs/kimi-backend.md.
Note
Cline β Cline CLI, supports any OpenAI-compatible provider (including SAP AI Core, Azure OpenAI, etc.)
Install: bun add -g cline | cline --version
Config: ~/.cline/data/globalState.json + secrets.json β configure provider and model before use.
Headless mode: cline -y "task" β auto-approves all actions and exits when done.
SAP AI Core example: set provider to sapaicore, model to anthropic--claude-4.5-opus.
Backends do not have to be named after the CLI they run. A custom key (e.g. a model nickname) keeps full CLI-specific behaviour β permission-bypass flags and stdin prompt delivery β as long as Maestro can tell which CLI it wraps. Resolution order:
- the backend name itself (
claude,codex,gemini,kimi,cline), - the
providerfield (anthropic/claudeβ Claude,openai/codexβ Codex,google/geminiβ Gemini,moonshot/kimiβ Kimi,clineβ Cline), - the binary basename of
cmd(claude,codex,gemini,kimi,cline).
model:
default: fable
backends:
fable:
provider: anthropic # β claude exec path (--dangerously-skip-permissions, -p, prompt via stdin)
cmd: claude --model claude-fable-5 --effort xhigh
fast:
provider: openai # β codex exec path (exec, bypass flag, prompt via stdin)
cmd: codex --profile fastA backend that matches none of the above falls back to the generic exec path: prompt_mode applies, no permission-bypass flag is added, and Maestro logs a startup warning naming the backend. Use the generic path only for genuinely custom CLIs.
Plain claude -p text mode prints no parseable token total, and codex exec text mode only prints a fuzzy single total β so a worker's tokens_used_total and USD cost are unreliable or 0. Opt a claude or codex backend into structured usage capture with usage_stream: true:
model:
default: claude
backends:
claude:
cmd: claude
usage_stream: true # run claude in --output-format stream-json; capture tokens + cost
codex:
cmd: codex
usage_stream: true # run codex exec --json; capture split tokens (cost = virtual)
pricing:
input_usd_per_mtok: 1.25
output_usd_per_mtok: 10When enabled, the worker runs the backend in structured-stream mode (claude --output-format stream-json --verbose, or codex exec --json) and its NDJSON is piped through maestro stream-split, which writes the raw frames to a side-channel <slot>.jsonl (parsed for input/output/cache tokens) while keeping <slot>.log human-readable. The session then reports non-zero split tokens in maestro history --json and the /api/v1/fleet cost panel. Off by default; an operator-pinned --output-format (claude) or --json (codex) in extra_args overrides it. Claude reports its own total_cost_usd; codex does not, so its cost is virtual β computed from the configured pricing block (tokens-only $0 when no rates are set). (The pi backend captures usage natively and needs no opt-in.)
Kimi uses stream-json by default and needs no usage_stream opt-in. When its
stream carries native input_other, output, input_cache_read, and
input_cache_creation usage, Maestro feeds those fields into the same
watermark and split-cost path. See the Kimi runbook for the upstream telemetry
and live-budget limitations.
Claude Code 2.1.216 was exercised in the same structured worker shape used by Maestro, with the proxy URL/credential inherited from the environment (values were neither printed nor captured):
printf 'Reply with exactly the word PONG.\n' |
claude --model <model> --effort low -p \
--output-format stream-json --verbose \
--dangerously-skip-permissionsAll three translated upstreams completed successfully and emitted plausible,
non-zero usage on the terminal result frame:
| Requested/init model | Assistant model | Input | Output | Cache read | Total | total_cost_usd |
Frame note |
|---|---|---|---|---|---|---|---|
kimi-k3 |
kimi-k3 |
17,535 | 20 | 6,144 | 23,699 | 0.091247 | assistant output was 0; live cap under-counts output |
grok-4.5 |
grok-4.5-build |
24,762 | 22 | 1,280 | 26,064 | 0.125000 | assistant usage was all zero; live cap is terminal-only |
gpt-5.6-sol |
gpt-5.6-sol |
21,581 | 6 | 0 | 21,587 | 0.111585 | assistant usage was all zero; live cap is terminal-only |
This confirms that the terminal result is authoritative for history/cost
accounting, but it also finds a live-enforcement degradation: none of the three
routes supplied fully plausible input/output usage on assistant frames. Kimi
under-counted generated output until the result; Grok and Sol supplied no live
count at all. A sanitized Grok capture (identifiers/timing removed; frame shapes
and usage retained) lives at
internal/worker/testdata/claude_proxy_grok_4_5_stream.jsonl and is round-tripped
through stream-split in the Go test suite.
--effort low was harmless for every route: the deployed proxy accepted all
three calls, and current CLIProxyAPI model metadata declares a low reasoning
level for Kimi K3, Grok 4.5, and GPT-5.6 Sol. CLIProxyAPI's thinking translation
maps supported levels to the upstream request and strips the setting for a route
that declares no thinking support; Maestro therefore keeps emitting the normal
Claude --effort flag rather than special-casing model names.
Maestro now logs and persists both degradation scopes on the active backend attribution:
usage_unreliable_scope: live_budgetwhen assistant usage has a zero input/output field. A later complete result still makes history/cost exact, butworker_max_tokenswas not enforceable response-by-response for that segment.usage_unreliable_scope: accountingwhen a successful terminal result omitsusageor reports zero input/output. Token totals are then a lower bound, and the cost-observability API includes the session inusage_unreliable_sessionsinstead of dropping it as no activity.
In either scope, 0 tokens means unavailable β never progress. The live token
monitor does not synthesize a budget hit or kill from missing usage; the
stalled-progress watchdog remains driven by terminal/checkpoint, worktree/Git,
process/tmux, and PR-review signals rather than token counters. Operators using
a positive hard cap should therefore treat these three proxy routes as
degraded until CLIProxyAPI supplies non-zero assistant-frame input and output.
External dashboard comparison remains operator verification. The worker environment has proxy request credentials but no access to the external usage sink/dashboard, and current CLIProxyAPI usage-queue reads are destructive. The numbers above are the captured translated stream values, not an independently claimed dashboard match; keep issue #946 open until an operator compares these three request rows in the deployed dashboard.
When worker_max_tokens is positive, structured usage is no longer optional:
Maestro fails the worker start closed if the selected backend/output mode cannot
enforce a live ceiling. Claude, Pi, and OpenCode stop from their usage event
stream; Codex combines cumulative rollout token_count telemetry with its
native rollout budget inside the agent loop (--ephemeral is rejected).
Enforcement lags by at most one provider response, not by the orchestration poll
interval.
For Claude and Pi, worker_max_tokens counts input + output + newly written
cache tokens and excludes cache reads. Cache reads remain in session and cost
telemetry, but replaying the same cached context on later turns does not consume
the live ceiling again. Fleet exposes the current budget numerator separately as
token_budget_tokens_attempt with token_budget_measure: uncached_tokens.
Worker sessions receive no MCP tools by default. Attach project-specific MCP servers per backend with model.backends.<name>.mcp:
model:
default: codex
backends:
codex:
cmd: codex
mcp:
servers:
docs:
command: npx
args: ["-y", "@example/docs-mcp"]
symbols:
url: https://mcp.example.com/mcp
bearer_token_env_var: SYMBOLS_MCP_TOKEN
claude:
cmd: claude
mcp:
strict: true
configs:
- /path/to/project-mcp.jsonFor Codex workers, Maestro passes configured servers as -c mcp_servers... overrides. For Claude workers, Maestro passes --mcp-config and --strict-mcp-config when requested. Keep tokens in environment variables and reference their names from config.
Label a GitHub issue with model:codex, model:gemini, or model:cline to override the default backend for that specific issue:
issue #42 labels: enhancement, model:codex β runs with Codex
issue #43 labels: enhancement, model:cline β runs with Cline
issue #44 labels: enhancement β runs with default (claude)
Runs the orchestration loop. Every interval:
- Checks running sessions (kill dead, clean stale)
- Auto-merges PRs where CI is green (sequential by default, configurable via
merge_strategy). A green draft PR is automatically marked ready for review first (gh pr ready), unless its title/body carries an explicit WIP/Partial marker ([WIP]/[Partial]in the title, ormaestro:partial/maestro:wipin the body) β those drafts are deliberate and stay untouched. - Rebases PRs with conflicts
- Picks new issues to work on (up to
max_parallel - active) - Starts new workers for picked issues
maestro run # runs forever, 10m interval
maestro run --once # run once and exit (dry run / cron mode)
maestro run --interval 5m # custom interval
maestro run --prompt /path/to/worker-prompt.md # custom prompt baseShows current state as a formatted table.
maestro status # pretty table
maestro status --json # JSON outputExample output:
Repo: OWNER/REPO
Session prefix: prj
State file: ~/.maestro/<repo-hash>/state.json
Max parallel: 5
SESSION ISSUE STATUS PID ALIVE AGE TITLE
------- ----- ------ --- ----- --- -----
prj-1 #154 running 12345 yes 23m Add asset inventory endpoint
prj-2 #155 pr_open 12346 no 1h5m Fix auth refresh
Manually spawn a worker for a specific issue.
maestro spawn --issue 154
maestro spawn --issue 154 --prompt /path/to/custom-prompt.mdStop a specific session and remove its worktree.
maestro stop --session pan-1First-class pause/resume for a project's execution β no systemd unit or config file surgery needed.
maestro pause --config /path/to/project.yaml # stop selecting/spawning new issues
maestro resume --config /path/to/project.yaml # restore issue selection next cycleWhile paused:
- The orchestrator skips issue selection entirely and spawns zero new workers,
even when
maestro-readyissues exist. - An in-flight worker is not killed β it runs to completion and lands its PR normally (drain semantics are unchanged).
- The flag is persisted in the project state dir and survives a
systemctl --user restartof the maestro service; onlymaestro resumeclears it. - The supervisor stays alive and reports the paused state instead of treating
the idle project as a stall, and
GET /api/v1/fleetexposes a per-projectpausedflag (Mission Control shows a paused badge).
State is stored in ~/.maestro/<repo-hash>/state.json:
{
"sessions": {
"prj-1": {
"issue_number": 154,
"issue_title": "Add asset inventory endpoint",
"worktree": "/path/to/worktrees/repo/prj-1",
"branch": "feat/prj-1-154-add-asset-inventory-endpoint",
"pid": 12345,
"log_file": "~/.maestro/<project>/logs/prj-1.log",
"started_at": "2026-02-23T00:00:00Z",
"status": "running"
}
},
"next_slot": 2
}Session statuses:
runningβ AI agent is workingpr_openβ PR created, waiting for CI / reviewdoneβ PR merged and worktree cleaned upfailedβ Something went wrongconflict_failedβ Rebase failed, needs manual interventiondeadβ Process died unexpectedly
State writes are atomic (temp file + rename).
Each worker's output goes to ~/.maestro/<repo-hash>/logs/<session>.log.
maestro sends Telegram notifications via the OpenClaw gateway API at http://localhost:18789/api/v1/message:
- π Worker started for issue
- β PR merged successfully
- β CI failing / merge failed / rebase failed / worker died
- β° Worker running > 2h (might be stuck)
- π Rebase succeeded
The worker prompt is assembled from:
- A base prompt (from
worker_promptconfig or--prompt) - Issue number, title, and body
- Worktree path and instructions for creating a PR
The exact command depends on the selected backend. Examples:
# Claude
cd /worktree/path && claude --dangerously-skip-permissions -p < /path/to/prompt.txt
# Codex
cd /worktree/path && codex exec --dangerously-bypass-approvals-and-sandbox -C /worktree/path - < /path/to/prompt.txt
# Cline
cd /worktree/path && cline -y "<assembled prompt>"Older installations may still contain maestro run --once cron jobs. Do not
create one for a new project: migrate the YAML through
scripts/migrate-to-daemon.sh --dry-run, then let the single
maestro daemon --watch-store process schedule all project flows.
Register each project as one row in the unified config store. Each portable
project YAML may still set a distinct session_prefix and state_dir; apply it
through maestro project plan / maestro project apply instead of starting a
process per YAML:
# ~/.maestro/maestro-panoptikon.yaml
repo: BeFeast/panoptikon
project_id: 11111111-2222-4333-8444-555555555555
management_home:
kind: obsidian
path: /srv/example-vault/Dev/Areas/panoptikon
vault: Example Vault
vault_path: Dev/Areas/panoptikon
session_prefix: pan # workers: pan-1, pan-2, ...
state_dir: ~/.maestro/pan
local_path: /srv/example-src/panoptikon
worktree_base: /srv/example-worktrees/panoptikon
max_parallel: 5# ~/.maestro/maestro-myapp.yaml
repo: BeFeast/myapp
project_id: 66666666-7777-4888-8999-aaaaaaaaaaaa
management_home:
kind: obsidian
path: /srv/example-vault/Dev/Areas/myapp
vault: Example Vault
vault_path: Dev/Areas/myapp
session_prefix: app # workers: app-1, app-2, ...
state_dir: ~/.maestro/app
local_path: /srv/example-src/myapp
worktree_base: /srv/example-worktrees/myapp
max_parallel: 3Maestro runs from one unit β maestro daemon --watch-store β that drives
every project in a shared SQLite config store. There is no per-project service:
the retired maestro init wizard no longer generates maestro.service or a
launchd plist. Register projects with maestro project plan/project apply
(see Quickstart); the daemon hot-reconciles new rows without a
restart.
Note: User services require
loginctl enable-linger $USERto keep running when you're not logged in.
For a fleet, run one maestro.service that drives every project. maestro daemon runs an orchestrator + supervisor loop per project in a single process
plus one aggregating fleet dashboard on :8786. This replaces the old
per-project maestro@.service template (and the separate supervise/serve units)
β one unit instead of ~15.
Projects live in a SQLite config store, not per-project YAML files. Seed it once
from your existing ~/.maestro/maestro.d/*.yaml:
maestro config-store migrate --db ~/.maestro/maestro.db --dir ~/.maestro/maestro.dThen install and start the daemon unit (a maestro.service for the daemon ships
in the repo root):
cp maestro.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now maestro.service
# Check status β list-units shows ONE active maestro unit
systemctl --user list-units 'maestro*'
journalctl --user -u maestro.service -fProvider tokens/keys must not be literal Environment= values. Install one
owner-only service credential file and reference it with
MAESTRO_WORKER_CREDENTIALS_FILE; see the
worker credential boundary and migration runbook.
Generated workers receive values only at process start and persist names/path
references only.
The whole cutover (seed store β stop legacy units β start the daemon β verify
:8786/api/v1/fleet) is automated by scripts/migrate-to-daemon.sh:
scripts/migrate-to-daemon.sh # prompts before changing a running host
scripts/migrate-to-daemon.sh --dry-run # show the actions without applying themOn upgrade hosts, a compatibility guard detects project rows left in the old
~/.maestro/config.db: default CLI commands stay on that legacy store with a
warning, and the shipped service refuses to present an empty canonical fleet.
Run the dry-run/cutover above (or the explicit export/migrate commands printed by
the error) before switching to ~/.maestro/maestro.db.
The cutover is non-concurrent per project (it stops the legacy units before starting the daemon, so no project is ever driven by both). Rollback is supported because the legacy unit files stay on disk:
systemctl --user disable --now maestro.service
# regenerate per-project YAML from the store if you removed the originals:
maestro config-store export --db ~/.maestro/maestro.db --dir ~/.maestro/maestro.d
systemctl --user enable --now maestro@panoptikon maestro@myapp # re-enable old unitsAdding / removing projects at runtime. With the daemon you no longer create a
unit per project. Register a project through the genesis flow (strict validation +
an explicit project_id confirmation) and the daemon hot-reconciles it (no
restart); removal stays a separate explicit action:
maestro project plan --file ./new-project.yaml --db ~/.maestro/maestro.db --json
maestro project apply --file ./new-project.yaml --db ~/.maestro/maestro.db \
--confirm <project-id> --fingerprint <sha256-from-plan> --baseline <baseline-from-plan> --json
maestro config-store rm --db ~/.maestro/maestro.db <project>The fleet dashboard exposes the same as authenticated, audited endpoints β
POST /api/v1/fleet/projects (body {"config_yaml": "..."}) and
DELETE /api/v1/fleet/projects (body {"name": "..."}) β so you can add a
project from the UI. On SIGTERM (systemctl --user stop) the daemon drains
gracefully in-process: it stops claiming new issues and waits for in-flight
workers to finish before exiting (bounded by --drain-timeout, default 5m,
inside the unit's TimeoutStopSec=6min).
The Mission Control SPA lives in internal/server/web/mc/ and ships as a pre-built bundle committed under internal/server/web/static/mc/. CI rebuilds the bundle on every PR and fails the frontend-build job if the committed output drifts from a fresh build.
The frontend toolchain is pinned via the packageManager field in internal/server/web/mc/package.json and the matching bun-version in .github/workflows/ci.yml. Use the same bun version locally β Corepack will respect packageManager automatically, or install it explicitly:
bun --version # must match the pinned version in package.jsonWhen bumping bun, update both packageManager in package.json and bun-version in .github/workflows/ci.yml in the same PR so they cannot drift.
When CI fails with Committed MC bundle is stale, the fix is always to rebuild and commit β never gh pr merge --admin. The canonical recipe:
cd internal/server/web/mc
bun install --frozen-lockfile
bun run build
cd -
git add internal/server/web/static/mc/
git commit -m "chore: rebuild MC bundle"If the diff still appears after a clean rebuild, your local bun/vite versions disagree with CI. Verify bun --version matches the pin in package.json. Bypassing the gate with --admin is the failure mode this guard exists to prevent β the bundle that ships from static/mc/ is what users load, so a stale commit ships stale UI.
gh auth login # re-authenticate
gh auth status # verify token has repo accessFor private repos, ensure your token includes the repo scope.
Check the worker log for errors:
maestro logs <slot> # e.g. maestro logs pan-1Common causes:
- AI CLI not authenticated/configured β run
claude auth(orcodex auth/gemini auth); for Cline, configure provider credentials in~/.cline/data/globalState.json+secrets.json - AI CLI not found in PATH β verify with
which claude/which codex/which gemini/which cline, or use an absolute path in config:cmd: /usr/local/bin/claude - Git worktree creation failed (ensure the local repo clone is clean)
Maestro looks for config in this order:
--configflag pathmaestro.yamlin the current directory~/.maestro/config.yaml
Write a portable project config and register it with maestro project apply (see
Quickstart), or pass an explicit config path for a one-off run:
maestro run --config ~/.maestro/maestro-myapp.yaml- Verify your
issue_labelsconfig (or deprecatedissue_label) matches existing issue labels on GitHub - Check that issues aren't already assigned or have
exclude_labels - Run
gh api 'repos/OWNER/REPO/issues?state=open&labels=enhancement' --jq '.[].number'to confirm matching issues exist
maestro requires tmux to manage worker sessions. Install it:
# Ubuntu/Debian
sudo apt install tmux
# macOS
brew install tmuxIf a worker died and left a stale worktree:
maestro stop --session <slot> # cleans up worktree + state
# or force-kill:
maestro kill <slot>
# Manual cleanup if needed:
git -C /path/to/repo worktree remove /path/to/worktree --force# Check logs
journalctl --user -u maestro.service -f
# Verify the binary is at /usr/local/bin/maestro
which maestro
# Verify the config file exists
ls ~/.maestro/maestro-myapp.yaml
# Reload after editing the unit file
systemctl --user daemon-reload
systemctl --user restart maestro.service
# Ensure linger is enabled (required for services when not logged in)
loginctl enable-linger $USERMaestro sends a Telegram notification when a worker runs longer than 2 hours. You can manually kill and retry:
maestro kill <slot> # kills the stuck worker
maestro spawn --issue <number> # retry the issuegithub.com/befeast/maestro(this module)gopkg.in/yaml.v3(config parsing)ghCLI (GitHub operations)git(worktree management)claude/codex/gemini/clineCLI (agent invocation β at least one required)
Inspired by agent-orchestrator (ao) β a great tool for parallelizing AI coding agents across git worktrees. maestro started as a replacement for our ao + shell scripts setup, borrowing the core idea of session-per-issue isolation in worktrees and rewriting it in Go for faster iteration cycles and better process reliability.
MIT β Copyright (c) 2026 Oleg Kossoy
- Free-agentic test pass: opencode produced this commit.



