@mozilla-ai/pi-otari

Pi is a minimal, extensible terminal coding harness, while Otari is an AI control plane and gateway for routing model requests, managing provider credentials, and tracking usage, budgets, and traces. This extension connects them so Pi can use Otari-managed models.

Demo

Requirements

• Pi 0.81.0 or newer, installed and available as pi (older versions can install the package but the extension will remain disabled and show an upgrade message)
• Node.js 22.19.0 or newer
• An Otari workspace API key
• At least one upstream provider and model enabled in your Otari workspace

Install and use

1. Install the extension from npm:

   pi install npm:@mozilla-ai/pi-otari

2. Start Pi:

   pi

3. Run /login otari and enter your Otari workspace API key in Pi's secret authentication prompt. This is API-key authentication, not OAuth: the prompt is separate from chat, so the key is not added to model context or sent to an LLM.

   Pi stores the credential in ~/.pi/agent/auth.json, a plaintext file created with user-only permissions (0600). Keep that file out of source control and untrusted backups. Run /logout otari to remove the stored credential.

4. Make Otari models available in Pi:

   • Run /scoped-models.
   • Search for otari.
   • Enable the models you want to use.
   • Press Ctrl+S to save the scope.

5. Run /model and select one of the enabled otari models.

6. Send a prompt normally. No Otari-specific slash command is required. When an Otari model is selected, Pi's status area shows Otari → <model-id>.

Pi sends requests for the selected provider to ${OTARI_BASE_URL}/chat/completions, which is https://api.otari.ai/api/v1/chat/completions for hosted Otari. Local Pi tools continue to run according to your Pi configuration.

To list the Otari models Pi currently knows about from a shell, run:

pi --list-models otari

NOTE: this prints Pi's cached catalog and does not contact Otari; see Model discovery for when the cache is refreshed.

Update or remove

pi update npm:@mozilla-ai/pi-otari
pi remove npm:@mozilla-ai/pi-otari

Install and use on omp

The same package is an omp plugin: omp reads the omp.extensions manifest (and ignores the Pi one), while Pi ignores the omp manifest, so one npm package serves both hosts.

1. Install the plugin:

   omp plugin install @mozilla-ai/pi-otari

2. Log in with your Otari workspace API key, either from a shell or inside the TUI:

   omp login otari

   This is the same masked API-key prompt as on Pi, not OAuth; the key is stored in omp's credential store and wins over OTARI_API_KEY, exactly like Pi's /login otari. For CI and containers, set OTARI_API_KEY instead.

3. Pick an otari model with /model and prompt normally. omp discovers the Otari catalog through the extension and shows every authenticated model; there is no /scoped-models step. The status line shows Otari → <model-id>.

Differences from the Pi extension

• Model cache: omp caches discovered models in its own model store with a 24-hour TTL instead of refreshing on every /model open. Run omp models refresh after enabling or removing models in Otari. Switching OTARI_BASE_URL between deployments may serve the previous deployment's cached list until a refresh.
• Model list: omp models otari lists the Otari models omp currently knows.
• Status updates: the Otari → <model-id> status line refreshes at session start and at each turn; omp has no model-select event.
• Subagent routing: not available on omp. The Pi feature integrates with pi-subagents, which is Pi-only, and omp's before_subagent_spawn event does not carry the subagent's task text that Otari needs to recommend a model.
• Guardrails: supported, with the differences listed under Guardrails.
• Everything else — OTARI_BASE_URL, OTARI_MODELS, OTARI_WEB_SEARCH/OTARI_WEB_FETCH with refusal retry, reasoning levels, the Otari-Conversation-Id header, and the diagnostics in Troubleshooting — behaves the same. Read pi as omp in those sections (for example ~/.omp/agent where ~/.pi/agent is named).

Model discovery

After login and during provider refresh, the extension queries {OTARI_BASE_URL}/models (https://api.otari.ai/api/v1/models for hosted otari) with the workspace token. Only models available through providers enabled for the authenticated workspace are registered. If the hosted endpoint responds with 404 or 405, the extension reports that hosted model discovery is unavailable. It does not request a public catalog or substitute models outside the authenticated discovery response.

The model list is a cache

Otari's catalog is dynamic: workspaces can enable and remove providers and models at any time. Pi stores the last discovered list in ~/.pi/agent/models-store.json and shows that list until the next refresh. In interactive mode Pi refreshes in the background at startup, after /login otari, and whenever you open /model. Print mode and pi --list-models read the cache only.

The cache belongs to one Otari deployment. Pointing OTARI_BASE_URL at a different host, such as switching between hosted and self-hosted Otari, drops the previous deployment's entries, and the list stays empty until the next refresh. Changing only the API prefix on the same host keeps them, since the deployment is the same. Refresh after adding or removing models in Otari: until then, entries from the previous catalog stay listed, and a request to one that no longer exists fails with an error from the gateway. Pi warns you when a previously selected model is missing from the refreshed list, so you can pick a current one.

Wrong API prefix

If discovery gets 404 from a self-hosted gateway, the extension probes the other well-known API root's public health route, without sending the token, and shows a warning naming the exact OTARI_BASE_URL to set. Otari 0.6.0 and newer serve /api/v1; older gateways served /v1.

If no models are found, provide one or more explicit Otari selectors before starting or restarting Pi:

export OTARI_MODELS="anthropic:claude-sonnet-5,mistral:mistral-medium-3-5" # optional fallback or additional selectors
pi

These selectors are registered as given, and Otari must have the corresponding provider and model enabled for the workspace. When discovery succeeds and its list does not include one of them, the extension warns once, naming the selector and, if the same model is listed under another provider prefix, the current selector to use instead. The entry itself stays registered until you update or remove it in OTARI_MODELS and restart Pi.

Web search and web fetch

When the connected Otari deployment offers its gateway-run web tools, every Otari request declares them: with otari_web_search the model can search the web mid-completion, and with otari_web_fetch it can read a public URL. Otari runs both server-side, and the exchange stays out of Pi's transcript while its token usage is folded into the request's totals. Otari bills each successful call under the workspace's Web Access policy. No setup is needed beyond an Otari deployment with a search backend configured (for search) or web_fetch_enabled (for fetch, which Otari leaves off by default). Set OTARI_WEB_SEARCH=off or OTARI_WEB_FETCH=off to stop declaring either tool. Only chat completions sent to OTARI_BASE_URL for otari/* models carry the declarations; models from other Pi providers are never affected.

Fetch lets the model send GET requests to arbitrary public URLs, within the workspace's domain policy, and fetched pages can contain prompt injection. Turn it off with OTARI_WEB_FETCH=off, or restrict the workspace's allowed domains in Otari, if that outbound access is unacceptable.

The extension learns availability from the gateway's tools catalog (GET {OTARI_BASE_URL}/tools) whenever the model list refreshes, and Pi's status line shows Otari → <model-id> · web search · web fetch, naming each tool while it is offered. A deployment whose catalog route is unreachable, such as a hybrid gateway, is probed optimistically instead: requests keep declaring both tools until the gateway refuses one. When the first request after a refresh that declares a tool is rejected with a 400, 403, or 422, it is retried without the last tool the gateway has not yet accepted (fetch before search), and then without the next, until one attempt succeeds or none is left. The tool dropped just before a success was the problem (no search backend configured, fetch not enabled, the tool not allowed for the workspace, or a gateway too old to know it): it stays off until the next model refresh, and a warning names the gateway's reason. A tool dropped earlier than that is tried again on the next request, so one refused tool never switches off the other. If the same client error survives every retry, it is shown as usual and both tools stay on. Once the gateway has accepted a declaration, later errors never drop that tool.

Reasoning levels

Models that Otari discovery marks as reasoning-capable expose Pi's minimal, low, medium, high, xhigh, and max reasoning levels. Models without that capability use Pi's conservative non-reasoning default. The extension forwards the selected level unchanged. Pi's default remains medium unless the user configures or selects another level.

Otari discovery does not yet provide each model's supported reasoning levels, so the levels exposed for a reasoning model are optimistic: an upstream model may reject a level it does not support. The extension preserves that error without silently retrying at a different level or without reasoning. When the upstream error reports supported values, they appear in Pi's error message.

Subagent routing

With pi-subagents installed, the extension can ask Otari which model a new subagent should run on. A subagent starts with an empty prompt cache, so the moment it is spawned is where a cheaper model costs nothing. Otari puts the task to a decision model and recommends the cheapest candidate that should do it well on the first attempt.

Routing is off by default. Turn it on in Pi's settings, globally in ~/.pi/agent/settings.json or per project in .pi/settings.json (Pi reads a project's settings only once you trust the project):

{
  "otari": {
    "subagentRouting": {
      "enabled": true,
      "candidates": {
        "openai:gpt-5-mini": "Simple, mechanical work: find, search, read and report.",
        "anthropic:claude-sonnet-5-5": "Moderate reasoning: contained code changes, tests.",
        "anthropic:claude-opus-5-5": "Hard reasoning: design choices, subtle bugs, large refactors."
      }
    }
  }
}

candidates is optional. Each key is an Otari model id, and each value says what the model is for (or is null). Without candidates, Otari chooses among its own list for Pi. Models that Pi cannot run, because discovery did not list them or there is no credential, are left out of the request.

When the parent model's message ends, the extension asks Otari about each single subagent launch in it, all at once. It sends the agent name, the task and the parent model, waits at most 3 seconds, and starts the subagent on otari/<recommended model>. A thinking level set on the launch's own model, such as :high, is kept when the recommended model supports reasoning. A notice shows the choice. If anything fails, such as a timeout, an error from Otari, or a model Pi cannot run, the subagent starts on the model it would have had anyway, and the notice says why.

Limits:

• It needs Pi 0.99.0 or newer, and an Otari API key from /login otari or OTARI_API_KEY.
• It needs an Otari gateway that recommends models for Pi (mozilla-ai/otari#2198), with a decision provider configured. Standalone (self-hosted) deployments serve the route.
• Only single launches are routed. Workflows, parallel tasks, chains, /run, and other launches that do not go through the subagent tool call start on their usual model.
• Otari is asked when the message ends, before Pi checks each tool call. A launch that Pi or another extension then blocks has already been sent to Otari.
• The recommended model counts as an explicit model in pi-subagents, so it wins over an agent's own model:. An enforced subagents.modelScope can still refuse it.

Guardrails

Pi obeys the same Otari agent guardrails as Claude Code and Codex: the rules in .otari/guardrails.yml or .otari/guardrails/*.yml in your repository, and in ~/.otari/. The extension does not interpret the rules. It shells out to the local otari hook CLI before each bash, read, edit and write tool call, and again when the agent is about to stop.

• A blocked tool call is refused, and the model sees the reason from otari.
• When a stop check fails at the end of a completed run, the extension adds the reason to the session and asks the model to continue once. It never forces a second continuation in the same run, and it never resumes a run you aborted or that ended in an error.
• Advisory feedback meant for the model, such as a failed judge gate, is added to the session without forcing a continuation.
• An advisory systemMessage from otari is shown as a notification.

Guardrails are active only when the otari binary is on PATH (or set OTARI_HOOK_BIN) and a guardrails file exists, searching from the working directory up to the git root and then ~/.otari/. Set OTARI_GUARDRAILS=off to disable them. If otari cannot be run, times out after about 20 seconds or exits unexpectedly, the action is allowed and you get a single warning.

Install an otari release with --harness pi support for full fidelity, including the commands Pi ran in the session. With an older otari, the extension detects the missing support once and sends Claude Code-shaped payloads instead, without the session's command list on stop checks.

On omp, guardrails run through omp's tool_call and session_stop events, and otari is called with the Pi harness, since omp's tools take the same inputs. They differ from Pi in a few ways:

• A hashline edit that patches several files is checked once per file and refused if any file is blocked.
• The reason for a forced continuation reaches the model as a hidden message, so it is also shown to you as a warning.
• Advisory context returned on a tool call reaches the model along with the tool result.
• Stop checks do not run for subagents, which omp never stops through session_stop.

Non-interactive authentication

For CI, containers, and other noninteractive environments, provide the API key through OTARI_API_KEY:

OTARI_API_KEY=tk_example pi

A key stored through /login otari takes precedence over OTARI_API_KEY. Running /logout otari removes the stored key, but Pi will continue using OTARI_API_KEY if it is set.

Self-hosted Otari

export OTARI_BASE_URL=https://otari.example.com/api/v1
pi

OTARI_BASE_URL must include the gateway's API prefix, because Pi appends /chat/completions and discovery appends /models to it. Otari 0.6.0 and newer serve /api/v1; gateways older than 0.6.0 served /v1. A bare origin such as https://otari.example.com is rejected. For a gateway on your own machine, use http://localhost:8000/api/v1.

Then run /login otari. For noninteractive use, set both OTARI_BASE_URL and OTARI_API_KEY.

HTTP is accepted only for loopback development endpoints.

Configuration

Privacy and security

Model requests using otari/* pass through Otari and the selected upstream provider. Each of those requests carries Pi's session id in an Otari-Conversation-Id header, which Otari uses to group a session's requests into one trace. The extension does not maintain its own credential file. When you use /login otari, Pi stores the API key in ~/.pi/agent/auth.json; when you use OTARI_API_KEY, the key remains environment-provided. The extension stores no prompts, responses, tool content, or telemetry. Pi persists provider model metadata in its native model store. Discovery rejects redirects and sends the token only to the configured model-discovery endpoint. When discovery returns 404 from a self-hosted gateway, the extension also requests that gateway's public health route on the other API prefix, again without the token. With subagent routing on, the extension also sends, for each single subagent launch in the parent model's messages (even one that is later blocked), the subagent's task, agent name, model ids, Pi's session id and the tool call id to {OTARI_BASE_URL}/routing/recommend, with the token and without following redirects. The session id lets Otari relate the launches of one session. A trusted project's .pi/settings.json can turn routing on, so trust only projects you would let send subagent tasks to Otari.

Troubleshooting

• “pi-otari requires Pi 0.81.0 or newer”: run pi update, then restart Pi. The package uses wildcard Pi peer dependencies, as required for Pi packages, and checks host compatibility at runtime instead of installing a second copy of Pi.
• No Otari models in /model: run /scoped-models, search for otari, enable models, and press Ctrl+S. If no models are available there, set OTARI_MODELS before starting or restarting Pi.
• “Otari returned no models for this workspace”: discovery succeeded but the workspace has no enabled provider or model. Enable one in Otari, then open /model to refresh; until then /model lists no Otari models.
• Missing credentials: run /login otari, or set OTARI_API_KEY before starting or restarting Pi.
• 401/403: Otari rejected the key used for discovery. Run /login otari with a valid replacement key, or set OTARI_API_KEY and restart Pi; then confirm workspace access. One possible cause is a stale key saved with /login otari, which takes precedence over OTARI_API_KEY; run /logout otari to fall back to the environment variable. The cached model list stays in place until the key is fixed.
• Unknown model: the selected provider or model is not enabled in your Otari workspace. Enable it in Otari, refresh the provider, or select a different Otari model in Pi.
• “Otari refused its web search tool: …”: the gateway rejected the otari_web_search declaration, so the request was retried without it and web search is paused until the next model refresh. The quoted reason is the gateway's own: configure a search backend (a web_search_provider key or web_search_url) or enable web search for the workspace in Otari. Set OTARI_WEB_SEARCH=off to stop declaring the tool.
• “Otari refused its web fetch tool: …”: the same, for the otari_web_fetch declaration. Enable fetch on the deployment (web_fetch_enabled) or allow it for the workspace in Otari, or set OTARI_WEB_FETCH=off to stop declaring the tool.
• “Otari (at …) does not list …”: that selector is not in the model list Otari returned for the configured URL. Its provider or model was disabled, or the model moved to another provider prefix, as with hosted Otari's retired mzai: prefix. Select a current model in /model; if the selector comes from OTARI_MODELS, update or remove it there.
• “400 status code (no body)” on a prompt: Otari rejected the request; its reason travels in a detail field that Pi's OpenAI client does not display (a direct curl to /chat/completions shows it). When the selected model is missing from the discovered list, the extension's explanation precedes this line. Otherwise, check in Otari that the model's provider is enabled and has a credential, or select a model from another provider in /model.
• “hosted model discovery is unavailable”: The hosted /models endpoint returned 404 or 405. No public catalog fallback is supported. Retry discovery when the service is available; if the error persists, contact the Otari service operator.
• “Otari model discovery returned HTTP 404 … Set OTARI_BASE_URL=…”: OTARI_BASE_URL has the wrong API prefix for that gateway. Set it to the URL shown and restart Pi. Otari 0.6.0 and newer serve /api/v1; older gateways served /v1.
• “Could not refresh otari; showing cached models”: this is Pi's summary. The extension's own warning next to it has the cause and, where possible, the fix.
• Models listed that no longer exist, or new ones missing: the list is a cache. Open /model to refresh it. See The model list is a cache.

Contributing

See CONTRIBUTING.md for development, testing, dependency updates, and release instructions.

License

Apache-2.0