Skip to content
maestro
Esc
  • IntroductionWhat OMP Maestro is, what it installs, and which parts are Maestro's own code.
  • InstallationInstall Maestro with npx or bunx, pick skill libraries, log in to providers and give the router a key.
  • EnsemblesThe three model ensembles — mix, anthropic and openai — and every role they assign.
  • Jev RouterHow Maestro's router uses TypeSafe Jev for main-turn downgrades and subagent worker classes, and how it fails open.
  • SkillsThe skill libraries Maestro can install, who made them, and how to add your own.
  • CommandsEvery command Maestro adds, plus the omp and ponytail commands it leans on.
  • ConfigurationCustomise roles, fallback chains, ensembles and skill libraries — and what Maestro does and doesn't touch.
  • Troubleshooting & FAQFixes for common setup problems and answers to frequent questions.

Installation

Install Maestro with npx or bunx, pick skill libraries, log in to providers and give the router a key.

Requirements

  • omp — the oh-my-pi harness. Required; the installer can install it for you.
  • Node.js (for npx) or Bun (for bunx). The package declares node >= 18.
  • git — only needed to install skills. Without it, plugins and the model setup still install.
  • A subscription for the providers your ensemble uses, and optionally a TypeSafe API key for the router.

Run the installer

Pick an ensemble by name. Without one you get the default, mix:

Terminal
$ npx omp-maestro              # mix — Claude leads, GPT codes (default)$ npx omp-maestro anthropic    # Claude only$ npx omp-maestro openai       # ChatGPT / Codex only$ bunx omp-maestro mix         # the same, with Bun
EnsembleWhat it isLog in to
mixClaude Opus orchestrates and plans, GPT Sol/Luna do the coding, Claude Sonnet does design and visionAnthropic + OpenAI Codex
anthropicClaude only: Opus thinks and plans, Sonnet codes, Haiku handles the small stuffAnthropic
openaiChatGPT/Codex only: GPT-6.1 Sol thinks and codes, GPT-6 Luna handles the small stuffOpenAI Codex

Not sure? Start with the one that matches the subscriptions you have — you can switch later without reinstalling.

What the installer does

  1. Checks your setup. It probes omp, git and the runner you launched it with (npx or bunx).
  2. Offers to install what's missing — and asks first, every time. omp is installed with the tool you launched from (bun install -g or npm install -g, the latter only when Bun is present, since omp runs on Bun), otherwise with omp's official installer. git comes from your system package manager: winget, Homebrew (or Xcode command-line tools), apt-get, dnf, pacman, zypper or apk.
  3. Asks one question: which skill libraries you want. All 6 start selected; ↑/↓ move, space toggles, enter confirms.
  4. Installs plugins: ponytail, then omp-maestro@0.1.2.
  5. Installs the chosen skills into ~/.agents/skills with the skills CLI. A library that fails is skipped with a warning; the rest carry on.
  6. Applies the ensemble by merging its modelRoles and retry.fallbackChains into your omp config. Roles the ensemble doesn't define are left untouched.
What runs, in order (mix, npx)
$ omp plugin install @dietrichgebert/ponytail$ omp plugin install omp-maestro@0.1.2$ npx -y skills add <repo> -g -y -a codex --skill <skills…>   # once per library you ticked$ omp config set modelRoles '{…your roles, with the ensemble's roles merged in…}'$ omp config set retry.fallbackChains '{…}'

Plugin source override

Set OMP_MAESTRO_SPEC to install the plugin from a different spec than omp-maestro@0.1.2 — useful when testing a fork.

After installing

Inside omp:

  1. Log in to the providers your ensemble uses: /login → Anthropic and/or OpenAI Codex (ChatGPT plan).
  2. Give the router a key. Export it, or put it in omp's env file:
Shell or ~/.omp/agent/.env
$ export TYPESAFE_API_KEY=…            # current shell# or add this line to ~/.omp/agent/.env:TYPESAFE_API_KEY=…
  1. Play. The status line shows 🧭 jev: ON when the router is live, NO KEY when it has no key, and OFF after /jev-route off.

CI and non-interactive runs

Without an interactive terminal the checklist is skipped and every skill library is installed. The installer also can't ask before installing missing tools, so it won't — make sure omp --version works first.

CI
$ npx omp-maestro anthropic < /dev/null

Re-running and updating

Re-running the installer is safe. It updates the plugins and skills and re-applies the ensemble you name — handy on a new machine, or to reset roles you've changed by hand.

Uninstalling

Terminal
$ omp plugin uninstall omp-maestro$ omp plugin uninstall @dietrichgebert/ponytail   # if you don't want ponytail either$ npx skills remove -g                            # pick skills to remove

Your model roles stay as they are — change them with /model.