@heihei0299/pi-switch20261011.0.0

Lightweight profile switcher for pi models.json

heihei0299 Published 8 days ago MIT ~739 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Reports 0

No reports yet.

Readme

pi-switch

A Native Desktop control plane for pi agent, with Linux CLI and TUI support.

Manage provider profiles and publish a local model-name gateway. The Native Desktop app is the primary GUI; the legacy WebView remains available through its --web rollback option.

English | 中文

Screenshots

The screenshots show the legacy WebView retained for Desktop --web rollback.

What it does

Manage provider profiles, model lists, and per-channel model exposure.
Preview and publish models to Pi through the Gateway page.
Route requests through a local proxy using the model name.
View request and token usage, and manage pi packages from Native Desktop or the legacy WebView.
Use the same Go core through Native Desktop, CLI, TUI, and the management API.

For architecture and detailed behavior, see WEBUI_GUIDE.md, docs/architecture.md, and docs/system-contract.md.

Install

From npm

npm install -g @heihei0299/pi-switch

# Or install through pi
pi install npm:@heihei0299/pi-switch

Build from source

Requires Node.js 23.6 or later and Go 1.24.2 or later.

git clone https://github.com/heihei0299/pi-switch.git
cd pi-switch
npm install
npm run build
node bin/pi-switch.js webui start --daemon

New CLI/npm versions support Linux amd64 and arm64 only. macOS and Windows are unsupported; historical releases are unchanged. See releases for available downloads.

Quick start

Start the management API (the legacy webui command name remains; its browser UI is retired):

pi-switch webui start --daemon

The management API remains available under /api/*; / displays the WebUI retirement notice. This command no longer opens a browser UI. The Desktop --web rollback path remains available while the formal GUI gate and deprecation steps are pending. Run environment checks with pi-switch doctor and stop the API with pi-switch webui stop. The terminal interfaces are also available: pi-switch tui or other pi-switch commands.

Use a model in Pi

Add a provider and expose its models in Profiles.
In Gateway, review the proposed changes and select Apply to Pi.
Start the proxy from Proxy, or run pi-switch proxy start --daemon.
In Pi, select pi-switch-res for Responses models or pi-switch-chat for Chat models, then choose an exposed model.

The management API binds to loopback by default. Binding to a non-loopback address requires a password; see the security guide.

Common questions

How do I switch models in Pi?

Open /model, select the published pi-switch-res or pi-switch-chat provider, and choose an exposed model.

Where is data stored?

Configuration and local request data are stored under /.pi-switch/. Pi's provider registry is /.pi/agent/models.json.

Development