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.

Configuration

Customise roles, fallback chains, ensembles and skill libraries — and what Maestro does and doesn't touch.

What gets written

Maestro touches exactly two omp settings, both maps keyed by role name:

  • modelRoles — which model plays each role, e.g. "task": "openai-codex/gpt-6.1-sol:medium". The part after the colon is the thinking level.
  • retry.fallbackChains — for each role, the models omp may move to when the primary fails.

Both the installer and /maestro merge: they set the roles the ensemble defines and leave every other role alone. Your theme, keybindings and other settings are never touched.

bin/omp-maestro.mjs
for (const [key, field] of [["modelRoles", "modelRoles"], ["retry.fallbackChains", "fallbackChains"]]) {  const current = JSON.parse(run("omp", ["config", "get", key], { capture: true }).trim() || "{}");  // Merge: only the roles this setup defines are replaced, the user's other roles stay.  run("omp", ["config", "set", key, JSON.stringify({ ...current, ...profiles[setup][field] })]);}

Inspect the result any time:

$ omp config get modelRoles$ omp config get retry.fallbackChains

Change a single role

Use omp's /model and its Roles view. Nothing in Maestro needs to know: once your roles no longer match an ensemble exactly, /maestro reports the active setup as custom. Running /maestro <name> again puts that ensemble's roles back.

The router follows your roles

The Jev Router reads @default, @smol and the four jev-* roles at the moment it routes, so changing any of them with /model changes where routed work goes — no restart needed.

Fallback chains

A chain is an ordered list. Entries are model selectors or other roles (@tiny, @smol, @default) — the judge chain, for example, is:

retry.fallbackChains → judge
{  "judge": [    "typesafe/jev-preview",    "@tiny",    "@smol",    "@default"  ]}

When and how omp moves along a chain is omp's retry behaviour, configured in omp's own retry.* settings. Subagents the Jev Router spawns get their role's model followed by that role's chain as their model list.

Ship your own ensemble

Fork omp-maestro and edit profiles.json. Every top-level key is an ensemble with a description, modelRoles and fallbackChains. The installer, /maestro (including tab completion) and the router all read this file — nothing else needs changing.

profiles.json
{  "my-ensemble": {    "description": "Claude leads, GPT codes, Haiku takes the small parts",    "modelRoles": {      "default": "anthropic/claude-opus-5-5:medium",      "task": "openai-codex/gpt-6.1-sol:medium",      "smol": "anthropic/claude-haiku-5-5:low",      …    },    "fallbackChains": {      "default": ["openai-codex/gpt-5.6-sol:medium","openai-codex/gpt-6-sol:medium"],      …    }  }}

Then run the installer from your fork with your ensemble's name. Point OMP_MAESTRO_SPEC at your published plugin so omp installs your profiles.json rather than the upstream package:

$ OMP_MAESTRO_SPEC=<your-package>@<version> node bin/omp-maestro.mjs my-ensemble

Skill libraries work the same way through skills.json — see Skills.

Router settings

Router thresholds are constants in extensions/jev-router.ts, not omp settings; edit them in your fork. The only runtime controls are /jev-route on|off|verbose|quiet (per session) and the TYPESAFE_API_KEY environment variable. Every threshold is listed in Tuning thresholds.