Maestro — Multi-Agent Orchestration for Claude Code

AI-powered multi-agent orchestration for Claude Code. Coordinate up to 5 parallel AI squads across complex software projects — with role-based specialisation, dependency ordering, token tracking, backup/restore, and full audit trails.

GitHub: github.com/Maestrodevs · Install: pip install maestro-fleet

Formerly Admiralty. Maestro was rebranded from the Admiralty Fleet Command System. In v4.0, the adm/admiralty CLI aliases and ADMIRALTY_* environment variables were permanently removed. Use mso and MAESTRO_* exclusively. The workspace directory is now .mso/ (auto-migrated from .adm/ on first mso dispatch). See MIGRATION-v4.md for the upgrade guide.

What It Does

Maestro turns Claude Code into a coordinated team. You define work as Orders (discrete tasks), group them into Sprints (voyages), and the Dispatcher launches up to 5 specialised Squads in parallel — each running as an independent Claude Code session in its own role.

Human (You)  →  LEAD (Claude, interactive)  →  Dispatcher (mso dispatch)  →  5 Squads

In the built-in nautical persona (the default), this reads:

Captain (You)  →  Quartermaster (Claude)  →  Fleet Admiral (mso dispatch)  →  5 Crews

The nautical persona is purely stylistic — same mechanics, different vocabulary. See maestro/docs/PERSONAS.md for persona reference and switching instructions.

Roles:

Installation

1. Install Maestro from public PyPI:

   pip install maestro-fleet
   

   To pin a specific version, append e.g. ==4.5.0. The Python import name is maestro regardless (so from maestro import … keeps working). Airgapped / restricted-egress operators: see maestro/docs/AIR-GAPPED.md for the private-index install pattern.

2. Activate your licence (issued via Polar; see https://polar.sh/tech127):

   mso licence activate <YOUR-KEY>
   

3. Verify the CLI is installed and the licence is active:

   mso version
   mso licence status
   

v4.0: Legacy CLI aliases have been removed. Use mso exclusively.

The wheel itself is openly distributed; the runtime licence check is the gate. Source remains private under proprietary licence; see LICENSE for the full terms. Air-gapped / restricted-egress environments: see maestro/docs/AIR-GAPPED.md for the staging-machine activation pattern and the egress allowlist.

Upgrading, uninstalling, or seeing a stale/inconsistent version? See maestro/docs/INSTALL-UPGRADE-UNINSTALL.md — covers the maestro → maestro-fleet package rename (the old package must be removed, not upgraded), user-vs-system scope shadowing, PATH/Scripts issues, and the full uninstall procedure.

Every doc referenced on this page ships inside the wheel itself. Run mso docs after installing to list all of them, or mso docs <topic> (e.g. mso docs install-upgrade-uninstall) to read one without leaving your terminal — no need to be online or find this repo again.

Then scaffold a workspace:

mso init --project MYPROJECT --directory my-workspace
cd my-workspace
mso dispatch --max-crews 3

To enable the Slack bridge for mobile control, run the setup wizard before starting the bridge:

mso bridge setup    # interactive configuration wizard (first-time setup)
mso bridge start    # start after setup is complete

Quickstart

pip install maestro-fleet
mso quickstart

mso quickstart verifies your environment, scaffolds a demo workspace, dispatches a three-order demo sprint, and prints a summary — all in one command. Full guide: maestro/docs/QUICKSTART.md.

For deeper configuration, prerequisite validation, project analysis, and CI-friendly --check mode: mso setup — see maestro/docs/SETUP.md.

Persona Quickstart

Maestro ships with four built-in personas. Switch with:

# Use corporate persona (professional, no nautical metaphors)
mso dispatch --persona corporate

# Use startup persona (casual, fast-moving)
mso dispatch --persona startup

# Use default (minimal, no character)
mso dispatch --persona default

# The nautical persona is active by default
mso dispatch  # same as --persona nautical

Or set it permanently in .mso/config/workspace.json:

{
  "persona": "corporate"
}

Full persona reference: maestro/docs/PERSONAS.md.

CLI Reference

# Dispatch & monitoring
mso dispatch      [--max-crews N] [--cleanup] [--stagger-delay S] [--timeout M] [--max-turns N] [--persona NAME]
mso status        [--once] [--compact]
mso hub           start [--port N] [--open] | stop | status                # multi-workspace dashboard (Team/Enterprise)
mso cleanup
mso squad         --crew {1-5} [--status | --watch | --cleanup]          # alias: crew
mso verify        [--voyage VOY-ID] [--skip-tests]

# Sprints (voyages), orders & review
mso sprint        create "Title" | list | status VOY-ID | reconcile [--dry-run]   # alias: voyage
mso bug           "description" [!high]
mso review        queue | show | approve | revise --notes T | reject --notes T   <ORDER-ID>

# Roles (per-role overlays — FTR-0186)
mso roles         list | show CODE [--core|--overlay-only|--json] | validate | diff CODE | migrate-paths

# Workspace lifecycle
mso init          --project ACRONYM [--directory PATH]
mso quickstart
mso setup         [--check]
mso update        [--dry-run] [--force] [--directory PATH]
mso config        models
mso projects      list | remove

# Usage / security / identity / audit (enterprise tiers)
mso usage         [--summary | --voyage VOY-ID | --order ID | --report]
mso security      scan [--json --severity-threshold HIGH] | review [--against REF --staged]
mso identity      init | add-user | add-group | user|group|acl <add|remove|list> | show
mso audit         anchor [--auto]
mso secrets       doctor | rotate --key KEY | scrub | list
mso data-flow

# Licence / MCP / bridge / hooks / backup
mso licence       activate <KEY> | status | deactivate | revalidate     # alias: license
mso mcp           list | add | remove | validate | show
mso bridge        setup | start | stop | restart | status | test
mso hooks         install | uninstall
mso backup        [--project ACRONYM] [--list]
mso restore       BACKUP_FILE [--force] [--dry-run]
mso version

All commands use the mso prefix exclusively (the adm alias was removed in v4.0). Run mso <command> --help for the full flag set per command.

See maestro/docs/CLI-REFERENCE.md for full documentation.

Enterprise Security

Maestro ships an enterprise control set: identity + capability ACL, a hash-chained audit trail with external anchoring, a secrets-provider abstraction (Azure Key Vault / AWS Secrets Manager / HashiCorp Vault / 1Password / OS keyring / env), a data-residency egress filter (permissive / restrictive / air-gapped / proxied), GDPR-aligned Article 15/17/18 rights tooling, and operator role separation.

Security posture is reviewed on a rolling basis — the most recent internal audit (2026-07-08, v5.0.4) hardened identity verification, audit-log fail-closed verification, the Hub web surface, the Slack bridge, and the crew guards, and added CodeQL / dependency / secret scanning to CI. Open findings are published transparently rather than hidden.

See:

• docs/security/OVERVIEW.md — posture, data-flow, controls, honest open-findings
• docs/security/COMPLIANCE.md — SOC 2 + ISO 27001 control self-assessment
• SECURITY.md — vulnerability disclosure policy

What's New

For the full per-release history (including the latest release) see CHANGELOG.md. Highlights since v4.0:

• v5.0.0 — Maestro Hub (major): a real-time, multi-workspace fleet dashboard — a FastAPI backend (mso hub start) aggregating live voyages/orders/crews/usage/reviews across every registered project plus a lifecycle WebSocket, and a Next.js frontend with voyage role-pipelines, a dependency graph, a token-usage chart, the review queue, and tier-gated Dispatch/Hold controls. Plus dispatcher-livelock (BUG-0326) and test-isolation (BUG-0327) fixes. Full guide: maestro/docs/HUB.md.
• v4.3.x — dispatcher reliability: per-crew worktree isolation (parallel squads), crash-safe finalization + watchdog, convergence gating (no silent archive on a failed merge), per-tick heartbeat, and a process-tree kill for hung crews.
• v4.2.0 — security posture hardening + mso usage --voyage fixes.
• v4.1.0 — v4 clean-break (legacy admiralty/adm purge completed).

v4.0.0 — Hard-cutover rebrand

• All legacy aliases removed. Legacy CLI entry points are gone. Use mso only. MAESTRO_* env vars exclusively. See MIGRATION-v4.md.
• Workspace directory: .adm/ auto-migrates to .mso/ on first mso dispatch. Use mso migrate-workspace --resolve for split-brain situations.
• mso migrate-workspace command added for manual migration and split-brain resolution.
• Default GitHub org configurable via workspace.json defaultGitHubOrg field.

What's New in v3.0.0

v3.0.0 — Admiralty → Maestro rebrand + persona system

• Rebrand to Maestro. CLI entry point: mso (legacy adm retained through v3.x). Package: maestro (legacy admiralty retained through v3.x). Environment variables: MAESTRO_* (legacy ADMIRALTY_* dual-read through v3.x). All shims removed in v4.0.
• Persona system. Four built-in personas: nautical (default, the heritage theme), corporate, startup, default (minimal). Switch with --persona flag, MAESTRO_PERSONA env var, or workspace.json. Custom personas supported via YAML. See maestro/docs/PERSONAS.md.
• Role renames. Canonical codes: PLN/BLD/TST/DOC/SEC/REL/LEAD. Legacy codes NAV/SHP/BOS/SCR/LKT/COX/QM remain as aliases and continue to work in all order JSON, role-paths config, and CLI flags.
• Dual-read workspace. .mso/ preferred, .adm/ fallback. Both are equivalent; existing .adm/ workspaces work without migration.
• CLAUDE.md persona injection. The Quartermaster (nautical) / LEAD (default) framing in CLAUDE.md is now persona-driven via templates.

What's New in v2.5.0

v2.5.0 — Licence backend (Polar.sh) + public wheel distribution + branch discipline

• mso licence CLI — activate <KEY> / status / deactivate / revalidate. Replaces the GitHub-collaborator auth gate. HMAC-signed local store at ~/.maestro/licence.json (mode 0600); per-customer signing secret in OS keychain. 14-day offline grace from each successful online validation.
• Polar.sh as the single licence integration. Selected over Lemon Squeezy / Paddle / Keygen-self-host on take rate, OSS alignment, and AU-tax MoR coverage.
• Public wheel distribution at maestrodevs/maestrodevs.github.io. The source repo stays private; the dist repo ships built wheels via a GitHub Pages PEP 503 simple/ index.
• Branch discipline enforcement (BUG-0004). voyageBranch is now load-bearing across three layers — dispatcher's _verify_dispatcher_branch, pretool branch_guard.py, and a "Branch discipline (mandatory)" section in every role prompt template.
• Public GitHub org: github.com/Maestrodevs (live).

What's New in v2.2.0

v2.2.0 — Releaser role expansion

• REL (Coxswain) is the terminal role for every sprint — opens the PR, monitors gh pr checks --watch, fetches Copilot review comments, applies/regresses/declines each, resolves review threads via GraphQL, writes the REL-to-LEAD.md handoff, and notifies the Human via the bridge
• Default REL model bumped to Opus 4.7 (claude-opus-4-7)
• One sprint = one branch = one PR — bundling forbidden by the branching policy

What's New in v2.1.0

v2.1.0 — Quality gates + workspace updates

• Quality gates — structured acceptanceCriteria in orders; TST validates, REL enforces. Three validation types: manual, command, file-exists. Two severity levels: blocking and advisory
• mso update — new command to propagate schema and template changes from the installed pip package into an existing .mso/ workspace without overwriting user data

What's New in v2.0.0

v2.0.0 — Architecture separation + adm CLI

• adm command — CLI renamed from the v1.x binary to adm for brevity (now mso in v3.0.0+)
• .mso/ folder — project artefacts live in .mso/ (or .maestro/ in v3.0.0+) in user projects
• CLAUDE.md layering — three-layer context system: project CLAUDE.md → .mso/claude.md → pip docs
• mso init scaffolds .mso/ with pre-filled CLAUDE.md layers from templates

See maestro/docs/VERSIONING.md for full version history and scheme.

Repo Structure

The wheel is openly downloadable; runtime use requires a valid licence key (see maestro/docs/LICENCE.md).

In user projects, Maestro artefacts live under .mso/ (scaffolded by mso init):

my-project/
├── .mso/             # Maestro artefacts
│   ├── claude.md     # Layer 2: Maestro orchestration context
│   ├── config/       # workspace.json, role-paths.json
│   ├── orders/       # active/, complete/, failed/
│   ├── voyages/      # active/, complete/
│   └── queues/       # orders/, bugs/, security/, ...
└── CLAUDE.md         # Layer 1: project architecture, stack, conventions

Glossary

Maestro uses role-neutral terminology by default. The built-in nautical persona adds a layer of seafaring vocabulary. Here is the full mapping:

Documentation

Every maestro/docs/*.md page below ships inside the maestro-fleet wheel itself — after installing, run mso docs to list them all, or mso docs <topic> to read one offline (e.g. mso docs install-upgrade-uninstall). The docs/ and docs/security/ pages are private-repo-only and not part of the pip package.

Security

Maestro runs entirely on your own infrastructure — no Maestro-operated servers, no telemetry, bring-your-own AI key. Automated security scanning (CodeQL SAST, pip-audit dependency scanning, and gitleaks secret scanning) runs on every push and weekly; results are in the badges above and the repository Security tab.

For security posture, validation, vulnerability reporting, and compliance:

• SECURITY.md — vulnerability reporting policy + severity scope
• docs/security/OVERVIEW.md — 1-page CISO-facing summary: data-flow, controls, honest open-findings
• docs/security/COMPLIANCE.md — SOC2 + ISO 27001 control self-assessment (supporting, not certifying)
• .well-known/security.txt — machine-readable security contact (RFC 9116)

Report vulnerabilities privately via GitHub Security Advisories — do not open public GitHub issues.

Requirements

• Python 3.9+
• Claude Code CLI installed and authenticated
• Anthropic API key with access to Sonnet 4.6, Haiku 4.5, and Opus 4.7

License

Proprietary — All Rights Reserved.

The Maestro framework is commercial software, owned and operated by Tech 127 Pty Ltd (Australia). Use is governed by the terms of the LICENSE file included in this repository. In summary:

• You may use the software for internal business purposes under the terms of a valid licence (issued at activation via Polar — see polar.sh/tech127).
• Redistribution, resale, sublicensing, and reverse engineering are strictly prohibited.
• All intellectual property rights remain with Tech 127 Pty Ltd.

The wheel published at maestrodevs.github.io is openly downloadable; the runtime licence check is the gate. Runtime use without a valid key is unauthorised and a breach of the licence.

For licensing enquiries, billing, or sales:

• GitHub Issues: github.com/Maestrodevs
• GitHub org: github.com/Maestrodevs
• Licence activation / pricing: polar.sh/tech127