pi-model-alias

Configurable first-class model aliases for Pi.

Install

Install the published package from npm:

pi install npm:pi-model-alias

This installs the extension for your Pi sessions. Start a new Pi session after installation.

For a project-local installation, use:

pi install -l npm:pi-model-alias

What it does

pi-model-alias adds short, configurable model aliases beside Pi's native models.

An alias works anywhere Pi accepts a model, including the model picker, command line, cycling, scopes, defaults, restored sessions, and RPC. Pi sends requests through the configured target model, so the target's authentication, headers, capabilities, and streaming behavior remain active.

Aliases can be providerless, or they can use a visible provider namespace such as my-co/fast. The visible alias name is separate from its target model.

Commands

Use /model-alias to open the action picker, or run an action directly:

/model-alias add
/model-alias remove
/model-alias list

add asks for an alias, lets you choose its visible provider namespace, and lets you select an available native target. You do not type the target model ID.

remove lets you select a configured alias and removes it.

list shows configured aliases, their targets, materialization status, and active diagnostics.

For example, an alias can expose fast or my-co/fast while routing to openai/gpt-5.

Configuration schema

The global configuration file is normally ~/.pi/agent/model-aliases.json.

The package ships schemas/model-aliases.schema.json. Use that artifact to validate manual edits.

{
  "version": 1,
  "aliases": [
    { "targetProvider": "openai", "targetModel": "gpt-5", "alias": "fast" },
    { "targetProvider": "openai", "targetModel": "gpt-5", "alias": "openai-fast", "provider": "openai" },
    { "targetProvider": "openai", "targetModel": "gpt-5", "alias": "my-fast", "provider": "my-co" }
  ]
}

Only version and aliases are allowed at the top level. Each alias entry requires targetProvider, targetModel, and alias. The optional provider field controls the visible namespace and defaults to providerless.

Aliases are unique case-insensitively across the configuration. An alias cannot collide with a native model ID. Alias names must match [A-Za-z0-9][A-Za-z0-9._-]{0,63}. Provider slugs must match ^[a-z0-9][a-z0-9-]{0,63}$.

Troubleshooting

If an alias does not appear, run /model-alias list and inspect its diagnostic.

model-aliases.json is the only persistent configuration file. If it is malformed or invalid, the extension reports the diagnostic and uses no aliases until you correct it. Older recovery copies are removed at startup.

Resolve the reported configuration error, then run /model-alias list again.

Compatibility

Pi 0.83.0 is the tested baseline. The bridge is feature-detected rather than version-gated, so a future Pi version can work when its required ModelRuntime seams remain compatible.

Missing version metadata does not block compatible seams. A missing or incompatible ModelRuntime disables aliases without changing native models.

Pi runtime packages are peer dependencies. Pi supplies them, and this package does not bundle them.

Manual-edit concurrency

Pi reads at most 64 KiB of configuration for each synchronous runtime access and publishes one immutable revision. Commands lock, reread, and reapply their change before commit, allowing three total candidate attempts.

Do not manually edit model-aliases.json while /model-alias is committing. Use an atomic-save editor for manual changes. An edit after the command's final comparison and before rename is unsupported.

Development

Clone the repository, install dependencies, and build the package:

npm install
npm run build

Install the local build in Pi when you need to test source changes:

pi install /absolute/path/to/pi-model-alias

Run the main development checks:

npm test
npm run preflight
npm run docs:check

Publishing to npm

Pushing a protected tag vX.Y.Z that matches package.json version triggers the GitLab pipeline to publish to npm with provenance using OIDC trusted publishing. No npm token is stored in CI.

Maintainer bootstrap, done once:

# The package must exist on npm before trust can attach.
npm publish --access public

# Configure the GitLab trusted publisher.
npm trust gitlab pi-model-alias \
  --project tsubus-root/misc/pi-model-alias \
  --file .gitlab-ci.yml \
  --allow-publish

npm trust list pi-model-alias

After bootstrap, each release is:

npm version <patch|minor|major>
git push origin --tags

The protected-tag pipeline runs these release jobs in order:

1. package-release checks tag/version parity, builds the package, creates the exact npm tarball, and writes first-parent Git history notes.
2. publish-npm publishes that tarball with the existing npm OIDC trusted publisher.
3. create-gitlab-release uploads the same tarball to the GitLab Generic Package Registry and creates or updates a GitLab Release with the notes and a permanent package asset link.

The release job uses only the short-lived CI_JOB_TOKEN through GitLab CLI auto-login. It does not use a personal access token or an npm token. Retrying create-gitlab-release is safe: it reuses the package asset and updates the existing Release without publishing npm again.

Fallback gate

No automatic fallback exists. A bridge, package, host-identity, authentication/header, or parity failure stops the release. A registry/picker fallback needs a new ADR, scope revision, and user decision.