Pi custom / variant model

← Back to skills

Pi's saved default only loads if the exact `provider/id` exists in its model registry. Pi ships a static bundled list per provider — so OpenRouter **routing-shortcut variants** (`:nitro` = sort by throughput, `:floor` = cheapest, `:exacto` = quality tool-use) and any brand-new slug are NOT in it. When the default doesn't resolve, Pi silently falls through to its built-in per-provider default (for openrouter that's `moonshotai/kimi-k2.6`) — looking like Pi "reset" your model. Fix = register the slug as a custom model so `find(provider, id)` matches.

Category: AI & Intelligent Agents
Repo: antigravity-awesome-skills
Path: skills/pi-custom-model/SKILL.md
Updated: 7/12/2026, 11:41:17 PM
Open on GitHubHow to Install

AI Summary

Pi's saved default only loads if the exact `provider/id` exists in its model registry. Pi ships a static bundled list per provider — so OpenRouter **routing-shortcut variants** (`:nitro` = sort by throughput, `:floor` = cheapest, `:exacto` = quality tool-use) and any brand-new slug are NOT in it. When the default doesn't resolve, Pi silently falls through to its built-in per-provider default (for openrouter that's `moonshotai/kimi-k2.6`) — looking like Pi "reset" your model. Fix = register the slug as a custom model so `find(provider, id)` matches. It is useful for LLM applications, agent orchestration, RAG pipelines, AI evaluation, and multi-agent workflows. Source: antigravity-awesome-skills (skills/pi-custom-model/SKILL.md).

Pi custom / variant model

When to Use

Pi's saved default only loads if the exact provider/id exists in its model registry. Pi ships a static bundled list per provider — so OpenRouter routing-shortcut variants (:nitro = sort by throughput, :floor = cheapest, :exacto = quality tool-use) and any brand-new slug are NOT in it. When the default doesn't resolve, Pi silently falls through to its built-in per-provider default (for openrouter that's moonshotai/kimi-k2.6) — looking like Pi "reset" your model. Fix = register the slug as a custom model so find(provider, id) matches.

Files (global)

  • ~/.pi/agent/settings.json — defaultProvider, defaultModel, defaultThinkingLevel
  • ~/.pi/agent/models.json — custom models, keyed by provider
  • ~/.pi/agent/auth.json — provider credentials (check the provider key exists)

Steps

  1. Confirm the slug is real before adding it (e.g. check the OpenRouter model/variant exists). A typo'd id also silently falls back.
  2. Confirm auth. The provider must have a key in auth.json (or an env var like OPENROUTER_API_KEY). No auth → the model is registered but unavailable → still falls back.
  3. Add the model to models.json under providers.<provider>.models. For a built-in provider (openrouter, anthropic, etc.) you only supply metadata — api, baseUrl, and auth are inherited from the bundled defaults. Example: 
    {
  "providers": {
    "openrouter": {
      "models": [
        {
          "id": "z-ai/glm-5.2:nitro",
          "name": "Z.ai: GLM 5.2 (nitro)",
          "reasoning": true,
          "thinkingLevelMap": { "xhigh": "xhigh" },
          "input": ["text"],
          "cost": { "input": 0.95, "output": 3, "cacheRead": 0.18, "cacheWrite": 0 },
          "contextWindow": 1048576,
          "maxTokens": 32768,
          "compat": { "supportsDeveloperRole": false, "thinkingFormat": "openrouter" }
        }
      ]
    }
  }
}
    Copy cost/contextWindow/compat from the base model (the variant shares them) — find the bundled entry in <pi-pkg>/node_modules/@earendil-works/pi-ai/dist/providers/<provider>.models.js. Don't hardcode generic 128k/16k if the real model is bigger.
  4. Set the default in settings.json: defaultProvider + defaultModel = the exact id. Leave defaultThinkingLevel as the user has it.
  5. Verify: pi --list-models | grep <id> shows it, and JSON parses. Optionally smoke-test: pi --provider <p> --model "<id>" "which model are you?".

Quirks

  • Exact match only. find() is exact provider+id — no fuzzy/colon-stripping for the saved default path. The slug in settings.json and models.json must be byte-identical.
  • Silent fallback. Pi prints no error when the default doesn't resolve; it just shows a different model in the footer. That's the tell.
  • Don't edit settings.json alone. Setting defaultModel to an unregistered slug does nothing — models.json is the actual fix.
  • enabledModels (optional) pins the model picker so Ctrl+P cycling can't drift back: "enabledModels": ["<provider>/<id>:<thinking>"].
  • Project override. A repo's .pi/settings.json overrides global. If a default reverts only inside one project, check that file first.
  • Restart Pi fully — the registry loads at startup.

Limitations

  • Adapted from davidondrej/skills; verify local paths, tools, credentials, and agent features before acting.
  • For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.

Related skills