---
slug: "pi-provider-mux"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/NikolaiUgelvik/pi-provider-mux@main/README.md"
repo: "https://github.com/NikolaiUgelvik/pi-provider-mux"
source_file: "README.md"
branch: "main"
---
<p>
  <img src="assets/header.png" alt="Pi Provider Multiplexer" width="1200">
</p>

# Pi Provider Multiplexer

A Pi extension that gives an existing provider additional identities. Each
identity gets its own Pi login and model namespace while reusing the source
provider's API implementation.

## What is it?

Provider aliases are useful when the same provider needs more than one account,
credential, or login context. The extension creates a live provider facade for
an existing provider:

- aliases appear as providers in Pi's model picker;
- each alias can be authenticated independently through Pi's normal login flow;
- requests and model refreshes are forwarded to the selected source provider;
- the alias name is preserved in model and assistant-message metadata.

The source provider is not duplicated. Its API behavior and model catalog remain
the source of truth, while Pi stores credentials for the alias separately.

## What commands it exposes

| Command | Arguments | Description |
| --- | --- | --- |
| `/login-alias` | `[alias]` | Interactively create an alias for a provider. If `alias` is omitted, Pi asks for it. |

Creating an alias is a two-step process:

1. Run `/login-alias my-openai` and choose the provider to wrap.
2. Run `/login my-openai` to sign in with credentials for that alias.

After authentication, the alias's models are available from `/model` and show
the alias provider ID, for example `gpt-5.4 [my-openai]`.

The extension does not add its own login or model-selection commands; `/login`
and `/model` are Pi commands used with the providers it registers.

## Configuration

Aliases are stored in:

```text
~/.pi/agent/login-aliases.json
```

The file maps an alias ID to the source provider ID:

```json
{
  "my-openai": {
    "source": "openai"
  },
  "work-anthropic": {
    "source": "anthropic"
  }
}
```

The `source` value must be a provider ID known to Pi. Alias IDs may contain
letters, numbers, `.`, `_`, and `-`, and must begin with a letter or number.
Credentials are not written to this file; Pi manages them in its usual
`auth.json`, keyed by the alias provider ID.

The configuration is loaded when the extension starts. Changes made manually
take effect the next time Pi starts. To remove an alias, delete its entry from
the file and restart Pi.

## Install

Install the packaged extension from npm:

```bash
pi install npm:pi-provider-mux
```

Or directly from GitHub:

```bash
pi install git:github.com/NikolaiUgelvik/pi-provider-mux
```

Restart Pi after installation. Pi loads the packaged TypeScript source through
its built-in jiti loader. npm and Git installs do not need TypeScript or a build
step.

For a local checkout, load the same TypeScript entry directly:

```bash
pi -e ./extensions/login-alias.ts
```

## Notes and limitations

Aliases for built-in providers and providers configured in `models.json` can be
available during startup model resolution. Providers supplied only by another
extension are discovered later, at `session_start`, so those aliases may not be
usable as Pi's initial or restored model.

When a source provider refreshes models, the alias forwards its alias-scoped
credential and model store to that refresh. Pi's provider API does not currently
support isolated provider cloning, so a source with mutable catalog state may
share refreshed models across aliases even though their credentials and stored
configuration remain separate.

## Development

Install dependencies and run the checks from the repository root:

```bash
npm install
npm run format
npm run lint
npm run dead-code
npm run typecheck
npm test
npm run check
npm run smoke:package
```

Pi loads `extensions/login-alias.ts` and its source modules through jiti. The
package publishes those TypeScript files directly, so no production build is
required.

The repository also has a Husky pre-commit hook that formats staged files and
runs the dead-code, typecheck, and test checks in parallel.

## License

Copyright 2026 Nikolai Ugelvik.

This project is licensed under the [Apache License, Version 2.0](https://github.com/NikolaiUgelvik/pi-provider-mux/tree/HEAD/LICENSE).