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.

Website: maestrodevs.com · Documentation: docs.maestrodevs.com · Install: pip install maestro-fleet

What It Does

Maestro turns Claude Code into a coordinated team. You define work as Orders (discrete tasks), group them into Sprints, 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. Run mso docs personas after installing for the persona reference and switching instructions.

Roles

Available models. Any role or order can run on any model Maestro supports: Fable 5.1, Fable 5, Opus 5, Sonnet 5 and Haiku 4.5 — plus the previous generation, still supported: Opus 4.8, Opus 4.7, Opus 4.6 and Sonnet 4.6. Choose a non-default with a per-order model field or a role overlay (.mso/config/roles/<CODE>.md); run mso docs config-models after installing for the full guide.

Installation

1. Install Maestro from PyPI:

   pip install maestro-fleet
   

   To pin a specific version, append e.g. ==5.12.1. The Python import name is maestro regardless (so from maestro import ... keeps working).

2. Activate your licence:

   mso licence activate <YOUR-KEY>
   

   Keys are issued with your subscription. For licensing enquiries, contact maestrodevs.com/contact.

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

   mso version
   mso licence status
   

The wheel itself is openly distributed; the runtime licence check is the gate.

Upgrading, uninstalling, or seeing a stale/inconsistent version? Run mso docs install-upgrade-uninstall — it covers the maestro to maestro-fleet package rename (the old package must be removed, not upgraded), user-vs-system scope shadowing, PATH and Scripts issues, and the full uninstall procedure.

Restricted-egress or offline operators: run mso docs air-gapped for the staging-machine activation pattern and the egress allowlist.

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: mso docs quickstart.

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

Personas

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

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

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

# 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: mso docs personas.

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 doctor        [--json] [--all-projects] [--explain]                    # read-only fleet self-check
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, orders & review
mso sprint        create "Title" | list | status VOY-ID | reconcile [--dry-run]   # alias: voyage
mso order         retry <ID> | skip <ID> | unskip <ID> | list
mso bug           "description" [!high]
mso review        queue | show | approve | revise --notes T | reject --notes T   <ORDER-ID>

# Roles
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

Run mso <command> --help for the full flag set per command, or mso docs cli-reference for the complete reference.

Documentation

Every documentation page ships inside the wheel itself. After installing, run mso docs to list them all, or mso docs <topic> to read one offline — no need to be online.

The hosted documentation site is at docs.maestrodevs.com.

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.

Maestro runs entirely on your own infrastructure — no Maestro-operated servers, no telemetry, bring-your-own AI key. Security posture is reviewed on a rolling basis, and open findings are published transparently rather than hidden.

Trust posture, threat model, and compliance mapping: maestrodevs.com/trust.

Report vulnerabilities confidentially via the contact form at maestrodevs.com/contact — please do not report security issues on any public tracker.

Workspace Layout

In your 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 config
│   ├── 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:

Requirements

• Python 3.9+
• Claude Code CLI installed and authenticated
• An Anthropic API key with access to the Claude 5 family (Opus 5, Sonnet 5) and Haiku 4.5; Fable 5.x where your plan includes it

Licence

Proprietary — All Rights Reserved.

Maestro is commercial software. Use is governed by the terms of the LICENSE file distributed with the package. In summary:

• You may use the software for internal business purposes under the terms of a valid licence.
• Redistribution, resale, sublicensing, and reverse engineering are strictly prohibited.
• All intellectual property rights remain with the licensor.

The published wheel 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: maestrodevs.com/contact.