@pi-orca/models

Model alias management for Pi Orca. Defines semantic model tiers (fast, balanced, thinker, coder) that map to provider-qualified model IDs, resolved through a four-level override cascade.

Overview

Model aliases let you reference models by intent rather than provider-specific IDs. Agent templates use aliases like fast or thinker, and the resolution layer maps them to concrete models (e.g., anthropic/claude-haiku-4-5). This decouples agent definitions from provider lock-in and lets users tune cost/quality trade-offs per-project.

The extension also injects aliases into Pi's built-in /model selector as a synthetic provider, so users can switch to alias-backed models via the standard Ctrl+L picker.

Installation

The package is part of the Pi Orca monorepo and loaded as a Pi extension:

{
  "pi": {
    "extensions": ["./dist/index.js"]
  }
}

Alias Resolution Cascade

Aliases resolve through four levels (highest priority wins):

Level	Source	Location
4	Session override	In-memory (set via /models set)
3	CLI environment	PI_MODEL_ALIAS_<NAME> env vars
2	Project override	<project>/.pi/orca/models.yaml
1	User defaults	~/.pi/agent/orca/models.yaml

Default Aliases

Bootstrapped on first run to ~/.pi/agent/orca/models.yaml:

Alias	Default Model	Description
fast	anthropic/claude-haiku-4-5	Lowest latency, lowest cost
balanced	anthropic/claude-sonnet-4-6	Good all-rounder
thinker	anthropic/claude-opus-4-6	Deep reasoning, higher cost
coder	anthropic/claude-sonnet-4-6	Best available for code generation

Slash Commands

/models (no args)

Opens an interactive TUI overlay showing all configured aliases.

Keybindings:

• Enter — Select the highlighted alias as the active model
• e — Reassign what the alias points to (opens model picker with type-to-filter)
• Esc — Close

Reassignments persist to the appropriate models.yaml file (project-level if the alias is defined there, otherwise user-level).

/models select <alias>

Activate an alias as the current model without opening the interactive UI. Supports tab-completion for alias names.

/models select fast

/models set <alias> <provider>/<model>

Reassign an alias to a different model. Persists to models.yaml.

/models set fast openai/gpt-4o-mini

/models reset

Clear all session-level overrides, reverting to config-based resolution.

/models setup

Bootstrap the default models.yaml if missing, or display current alias configuration.

/models debug

Diagnostic dump of registry state — shows how many models are registered, which are visible in the selector, and whether the synthetic provider entries match correctly.

Agent Tool

The extension registers a model_alias tool that agents can invoke programmatically:

// Resolve an alias to its provider/model-id
{ action: "resolve", alias: "fast" }
// → { provider: "anthropic", model: "claude-haiku-4-5", modelId: "anthropic/claude-haiku-4-5" }

// Set a session override
{ action: "set", alias: "coder", provider: "anthropic", model: "claude-opus-4-6" }

Synthetic Provider Integration

The extension registers a synthetic provider (pi-orca-models) with Pi's model registry. Each alias appears as a selectable model in the /model picker. When selected, the model_select event handler resolves the alias and calls pi.setModel() with the real model entry, preserving streaming protocol, context window, and cost metadata from the original model.

Alias Persistence in settings.json

When an alias is activated (via /models select, the interactive overlay, the /model picker, or session startup self-apply), the extension writes the alias reference back to settings.json as defaultProvider: "pi-orca-models" / defaultModel: "<alias>". This prevents the harness from overwriting the alias with the resolved real provider/model, ensuring the next session starts with the same alias as the default. Non-alias model selections via /model are unaffected.

CLI flag precedence

When the process is launched with both --provider <name> and --model <id> on the command line, the session_start self-apply is skipped — explicit CLI intent always wins over settings.json defaults. This is what allows @pi-orca/agents to spawn a child (--isolation process|tmux) on a different model than the user's default, and it also handles the manual pi --provider X --model Y case.

Cross-extension API

Other extensions resolve aliases without taking a package-level dependency on @pi-orca/models. The pattern (spec §8.6) lives in @pi-orca/core:

import { resolveAlias, resolveModel } from "@pi-orca/core";

resolveAlias("fast");                   // "anthropic/claude-haiku-4-5" or null
resolveAlias("pi-orca-models/fast");    // same — strips the synthetic-provider prefix
resolveModel("fast");                   // alias → provider/model-id cascade (§8.6.1)
resolveModel("claude-haiku-4-5");       // bare id → resolved through the SDK lookup adapter
resolveModel("anthropic/foo");          // literal passthrough when nothing else matches

At session_start, this extension registers a synchronous AliasResolver that reads from session overrides (Level 4), env-backed CLI flags (Level 3), and an in-memory snapshot of the project + user YAMLs (Levels 1+2). The snapshot refreshes after every persistAlias write, so /models set changes are visible to the next spawn without a session restart.

The pi-orca-models/<alias> form is supported so template authors can disambiguate "this is an alias" when the underlying model registry also offers a model with the same id.

Configuration Format

# ~/.pi/agent/orca/models.yaml
aliases:
  fast:
    provider: anthropic
    model: claude-haiku-4-5
    description: "Lowest latency, lowest cost"
  balanced:
    provider: anthropic
    model: claude-sonnet-4-6
    description: "Good all-rounder"

Architecture

src/
├── index.ts        # Extension entry point, TUI widget, slash command handler
├── resolver.ts     # Four-level cascade resolution, persistence
├── commands.ts     # Slash command implementations (set, reset, setup)
├── tool.ts         # Agent tool dispatcher
├── widget.ts       # Simple text widget renderer (non-interactive)
└── types.ts        # ModelAlias, ModelAliasConfig, ResolvedAlias
defaults/
└── models.yaml     # Bundled default aliases (copied on first run)

Dependencies

• @pi-orca/core — Path utilities, completion tree resolution, settings I/O (readPiSettings, writePiSettings)
• yaml — YAML parse/stringify for config files
• @earendil-works/pi-tui — TUI components (provided by Pi runtime)
• @earendil-works/pi-coding-agent — DynamicBorder component (provided by Pi runtime)

License

MIT