MAESTRO++ (Local Multi‑Agent Orchestrator)

Headless, stage‑gated multi‑agent system that orchestrates Codex (GPT‑5 High), Claude Code, Gemini CLI, Cursor Agent, and LM Studio/Qwen‑Coder. Ships with shared MCP tools and a local RAG engine.

Quickstart

# macOS deps
brew install python@3.11 git gh jq ripgrep node pnpm

# Python venv
python3.11 -m venv .venv && source .venv/bin/activate
python -m pip install -U pip
python -m pip install -r requirements.txt

# (Optional) Start LM Studio local server at http://localhost:1234

One‑shot run on any repo

python -m maestro.orchestrator run --repo "/abs/path/to/repo" --vision "Ship feature X"

• Creates maestro.yaml if missing (autodetects services)
• Uses council planning (Codex, Claude, Gemini, Cursor)
• Implements tasks in git worktrees with quality gates
• Updates the local RAG index incrementally

Commands

python -m maestro.orchestrator probe                 # which external CLIs available
python -m maestro.orchestrator bootstrap --repo .    # create maestro.yaml, VISION.md, index RAG
python -m maestro.orchestrator plan --repo . --vision "..."
python -m maestro.orchestrator implement --repo . [--open-pr]

MCP server registration (Claude example)

claude mcp add-json context-engine '{"type":"stdio","command":"python","args":["mcp/context_engine/server.py","stdio"]}'
claude mcp add-json test-harness  '{"type":"stdio","command":"python","args":["mcp/test_harness/server.py","stdio"]}'
claude mcp add-json repo-graph    '{"type":"stdio","command":"python","args":["mcp/repo_graph/server.py","stdio"]}'
claude mcp add-json consult-expert '{"type":"stdio","command":"python","args":["mcp/consult_expert/server.py","stdio"]}'

GitHub: create and push

# from repo root
source .venv/bin/activate

# initialize if needed
git rev-parse --is-inside-work-tree || (git init && git add -A && git commit -m "chore: bootstrap")

# create remote under yc-labs org (requires gh auth login)
REPO_NAME=devbuddy-maestro
ORG=yc-labs

gh repo create "$ORG/$REPO_NAME" --public --source . --remote origin --push
# or, if repo exists:
# git remote add origin git@github.com:$ORG/$REPO_NAME.git
# git push -u origin main

Customize gates

Edit maestro.yaml per service to match your build/lint/test commands. Python defaults use ruff, mypy, pytest; JavaScript defaults try pnpm then npm.