Orchestration

CLI orchestration

The daemon, lead/worker roles, team spawning and multi-project connectivity.

A single maestro-daemon process holds one isolated task per project WebSocket connection. Sessions are scoped as lead or worker: the lead orchestrates; workers are detached processes the lead spawns and reaps.

Subcommand surface

  • Orchestration — analyze, connect (alias tui), auth, init, hooks, team, disconnect, project, export.
  • Diagnostic — status, doctor, state, sandbox, version, help.
  • Introspection — agents, mcp, skills, plugins / plugin / marketplace, system-prompt.
  • Local (no network) — config, diff.

Connect & auto-detect

  • maestro connect [--no-tui] — register a session, subscribe to the project (and team) channel, pick up dispatched runs. Flags: --role lead|worker, --with-skill <slug,...>, --name <bot>, --team-channel <name>, --ephemeral.
  • maestro --name <bot> — persist a per-project bot name to ~/.maestro/projects.toml; the lead and every spawned worker adopt it for TUI labels and reports.
  • maestro status — show active connections; maestro disconnect — tear down. maestro clear-steering resets persisted operator directives.
  • Auto-detect: read git remote get-url origin → normalize to <provider>:<owner>/<repo> → match ~/.maestro/projects.toml → else Studio project lookup → else offer to create the project.
Team spawn
  1. 1

    Operator requests a team

    maestro team --dev 2 --review 1 --test 1

    Roles parsed by the CLI itself.

  2. 2

    Studio allocates a team channel

    POST /api/v1/agent-sessions/{lead}/team

    Server records the shared channel and worker count.

  3. 3

    Lead spawns detached workers

    --role worker

    maestro connect --no-tui --role worker --with-skill <slugs>, one per role.

  4. 4

    Shared channel orchestration

    ⚑ N steering

    Lead and workers subscribe to the team channel; the lead shows steering directives and completion reports.

  5. 5

    Workers reaped

    When the agent session ends, all spawned workers are terminated.

  6. Loops back until the verdict is approved

Operator steering

Type maestro <directive> in the lead TUI to inject [OPERATOR STEERING] live and persist it for the session; every later lead turn re-applies active directives. Reset with maestro clear-steering.

One daemon handles many projects and identities from a single machine — project manages the link set, doctor audits auth/config/workspace/sandbox, and sandbox/state expose the per-worker runtime.