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.

Troubleshooting & FAQ

Fixes for common setup problems and answers to frequent questions.

omp not found

The installer stops with omp is required when omp --version doesn't work and you declined (or couldn't be asked) to install it.

  • Just installed omp? Open a new terminal so your shell picks up the new PATH, then run the installer again.
  • Installing omp with npm requires Bun to be present — omp runs on Bun. Without Bun, the installer uses omp's official installer instead.
  • In CI, install omp before running Maestro; non-interactive runs never install tools. See the oh-my-pi README.
Check
$ omp --version

Skills were skipped

Skills will be skipped; plugins and the model setup still install means git or the runner (npx / bunx) wasn't found. Install git — on Windows, the installer can do it via winget — then re-run the installer. If a single library failed instead, its line shows ! failed, continuing without it; re-running retries it.

Status line says jev: NO KEY

The router can't see TYPESAFE_API_KEY. Everything else works; routing is simply off. Set the key and restart omp:

Shell or ~/.omp/agent/.env
$ export TYPESAFE_API_KEY=…# or, so every omp session sees it:# add TYPESAFE_API_KEY=… to ~/.omp/agent/.env

jev: OFF means routing was turned off with /jev-route off — turn it back on with /jev-route on. If routing seems idle with a key set, /jev-route status shows a judgeErrors counter.

Could not resolve a model

/maestro says could not resolve <model>; log in to that provider, then run /model when the new lead model isn't available — usually because you aren't logged in to its provider. The roles were still written. Run /login, then pick the model with /model (or run /maestro <name> again).

Jev Router: @default or @smol could not be resolved is the same problem for the router's two main-turn roles.

/maestro shows custom

custom means your current roles don't exactly match any ensemble — typically after changing a role with /model. That's fine. To go back to a stock ensemble, run /maestro mix (or anthropic / openai).

FAQ

Do I need both a Claude and a ChatGPT subscription?

Only for mix. The anthropic ensemble needs just Claude; openai needs just ChatGPT / Codex. Log in inside omp with /login.

Can I use only one provider?

Yes. Install with npx omp-maestro anthropic or npx omp-maestro openai, or switch later with /maestro anthropic / /maestro openai. Single-provider ensembles also keep their fallback chains within that provider.

Does the Jev Router need a TypeSafe API key?

Yes — set TYPESAFE_API_KEY in your environment or in ~/.omp/agent/.env. Without it everything else still works: the router stays out of the way, omp uses your model roles as normal, and the status line shows jev: NO KEY.

What happens if Jev is unavailable?

The router fails open. A missing key, a 1,800 ms timeout or any Jev error means plain omp behaviour: the turn runs on @default, and subagents use omp's normal roles. You never get a weaker model because the router hiccuped.

Will Maestro overwrite my existing omp configuration?

Only the model roles and fallback chains an ensemble defines. The installer reads your current modelRoles and retry.fallbackChains and merges into them; your other roles, theme, keybindings and settings are left alone.

Can I switch ensembles later?

Any time, with /maestro mix, /maestro anthropic or /maestro openai. The live session moves to the new lead model immediately. Re-running the installer with a different ensemble name works too.

How do I customise roles?

Use omp's /model (Roles view) to change any single role; /maestro then shows custom. To ship your own ensembles, fork the repository and edit profiles.json — the command, the installer and the router all read it.

How do I uninstall it?

Run omp plugin uninstall omp-maestro, optionally omp plugin uninstall @dietrichgebert/ponytail, and npx skills remove -g to pick skills to remove. Your model roles stay as they are — change them with /model.

Does it work in CI or other non-interactive environments?

Yes. Without an interactive terminal the skills checklist is skipped and every skill library is installed. The installer also won't offer to install missing tools — omp has to be present already.

What is Maestro's relationship to oh-my-pi?

Maestro is an omp plugin plus an installer, made by an omp user — not part of the omp project and not a replacement for it. omp, by Can Bölük and contributors, does all the actual work; Maestro configures it and adds the Jev Router and /maestro.

Still stuck? Open an issue with the installer output.