pi-setup

Setup wizard for pi — the minimal terminal coding harness.

Configure providers, models, thinking levels, and defaults through an interactive UI or standalone shell script.

Includes a web dashboard for monitoring your pi configuration at a glance.

Status: v0.2.1 — Dashboard added (Alpha); API may change between releases.

Features

Interactive /setup command — runs inside pi using built-in UI dialogs (select, input, confirm)
Standalone shell wizard (pi-setup) — bootstrap config before pi is even installed
Back navigation — every menu supports < Back to return to the previous screen
Auto-registration — saved providers are loaded on pi startup automatically
Multi-provider support — Anthropic, OpenAI, Google, XAI, OpenCode, Ollama, LM Studio, and custom endpoints
Model management — add, edit, and remove models per provider
Inline "set as default" — offered immediately after adding a model
Default model selection — set your preferred model and thinking level
Secure auth storage — API key references saved with 0600 permissions
First-run bootstrap — pi-setup standalone wizard creates provider config before pi can start (pi exits without a provider); install.sh links pi-setup onto your PATH
No-key providers preserved — local/Ollama endpoints without an API key are kept, not deleted on exit

Dashboard

The /pi-setup-dashboard command starts a localhost web UI (port 9330) that shows:

All configured providers with models, context windows, and reasoning support
Auth status (key presence, never the keys themselves)
Current defaults (provider, model, thinking level, theme)
Installed pi packages
Cross-links to sibling dashboards (e.g. pi-mega-compact on port 9320)

/pi-setup-dashboard        — start/open the dashboard
/pi-setup-dashboard-stop   — stop the dashboard server

The dashboard auto-detects pi-mega-compact's dashboard (if running) and links to it. Both dashboards cross-link each other.

See dashboard-server/README.md for architecture details.

Installation

Option 1: npm package (recommended)

pi-setup is published to npm as pi-setup. Install it through pi's package manager so the /setup command and /pi-setup-dashboard command are registered, and pi's auto-loader picks up the extension:

pi install npm:pi-setup

Then start (or restart) pi — the extension loads on startup, and /setup becomes available immediately.

Updating:

pi update --extensions

That's the entire extension install. No cloning, no copying files, no symlinks. The released package includes the pre-built dashboard bundle, so /pi-setup-dashboard works out of the box.

Option 2: Clone the Repo (development / shell-script-only)

Use this if you want to hack on pi-setup, run the standalone wizard without pi, or use the raw shell script. The repository's install.sh copies the extension into ~/.pi/agent/extensions/ and symlinks pi-setup onto your PATH so the pi-setup command works from anywhere.

git clone https://github.com/TheArchitectit/pi-setup.git
cd pi-setup
./install.sh
# Then run the standalone wizard from any directory:
pi-setup

If you only need the standalone setup wizard (no pi extension):

git clone https://github.com/TheArchitectit/pi-setup.git
cd pi-setup
chmod +x pi-setup setup.sh
./pi-setup
# or use the bash wrapper:
./setup.sh

Prerequisites

Node.js 18+ (for the extension and the dashboard build)
pi installed globally (npm install -g pi or via pi-coding-agent)
bash (for the shell script mode; not required if you only use Option 1 via npm)

Usage

Extension Mode

After installing the extension, start pi and run the /setup command:

pi
/setup

The wizard walks you through:

Provider management — add, edit, or remove LLM providers
Model configuration — configure models for each provider
Default model — choose which model pi uses by default
Thinking level — set default reasoning depth (off / minimal / low / medium / high / xhigh)

The wizard uses pi's built-in dialog system — select lists, text inputs, and confirmation prompts.

What Happens Behind the Scenes

Provider configs are saved to ~/.pi/agent/models.json
API key references are saved to ~/.pi/agent/auth.json (file permissions: 0600)
Settings (default model, thinking level) are saved to ~/.pi/agent/settings.json
Providers are immediately registered in the current pi session

Shell Script Mode

Run the standalone wizard without pi installed:

./pi-setup
# or:
./setup.sh

The standalone wizard:

Checks for pi and its config directory
Prompts you to configure providers
Asks for API keys (stored in ~/.pi/agent/auth.json with $$-escaped $ characters)
Lists and selects available models with full back navigation
Writes the config files that pi reads on startup

Every menu supports < Back to return to the previous screen. Text inputs can be cancelled with Enter (empty) to go back.

First-run note: Because pi exits when no provider is configured, run ./pi-setup before starting pi. Once a provider is saved, pi will start and the /setup extension will be available for later edits.

Configuration Reference

Config Files

File	Purpose	Permissions
`~/.pi/agent/models.json`	Provider and model definitions	`0644`
`~/.pi/agent/auth.json`	API key environment variable references	`0600`
`~/.pi/agent/settings.json`	Default model, thinking level, provider	`0644`

Provider Schema

Each provider in models.json follows this structure:

{
  "providers": {
    "provider-name": {
      "name": "Display Name",
      "models": [
        {
          "id": "model-id",
          "name": "Display Name",
          "reasoning": true,
          "input": ["text", "image"],
          "cost": {
            "input": 3,
            "output": 15,
            "cacheRead": 0.3,
            "cacheWrite": 3.75
          },
          "contextWindow": 200000,
          "maxTokens": 16384,
          "compat": {
            "supportsDeveloperRole": false
          },
          "thinkingLevelMap": {
            "off": 0,
            "minimal": 1,
            "low": 2,
            "medium": 3,
            "high": 4,
            "xhigh": 5
          }
        }
      ]
    }
  }
}

Model Schema

Field	Type	Description
`id`	`string`	Model identifier sent to the API
`name`	`string`	Human-readable display name
`reasoning`	`boolean`	Whether the model supports extended thinking
`input`	`string[]`	Supported input types (`"text"`, `"image"`)
`cost`	`object`	Per-token pricing (USD)
`cost.input`	`number`	Cost per 1M input tokens
`cost.output`	`number`	Cost per 1M output tokens
`cost.cacheRead`	`number`	Cost per 1M cached input tokens
`cost.cacheWrite`	`number`	Cost per 1M cache write tokens
`contextWindow`	`number`	Maximum context window in tokens
`maxTokens`	`number`	Maximum output tokens
`thinkingLevelMap`	`object`	Mapping of thinking level names to API values
`compat`	`object`	Provider compatibility flags
`compat.supportsDeveloperRole`	`boolean`	Set `false` for endpoints that reject `role: "developer"` (default: `false` via setup extension)

Settings Schema

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "high"
}

Field	Type	Values
`defaultProvider`	`string`	Provider name key
`defaultModel`	`string`	Model ID
`defaultThinkingLevel`	`string`	`off`, `minimal`, `low`, `medium`, `high`, `xhigh`

Supported Providers

Provider	API Type	Notes
Anthropic	`anthropic-messages`	Claude models, requires `ANTHROPIC_API_KEY`
OpenAI	`openai-responses`	GPT and o-series models, requires `OPENAI_API_KEY`
Google	`google-genai`	Gemini models, requires `GOOGLE_GENERATIVE_AI_API_KEY`
XAI	`openai-completions`	Grok models, requires `XAI_API_KEY`
OpenCode	`anthropic-messages`	Gemini via OpenCode proxy, requires `OPENCODE_API_KEY`
Ollama	`openai-chat`	Local models, no API key needed, default: `http://localhost:11434/v1`
LM Studio	`openai-chat`	Local models, no API key needed, default: `http://localhost:1234/v1`
Custom	any	Any OpenAI-compatible or Anthropic-compatible endpoint

API Keys

Pi reads API keys from environment variables. Add these to your shell profile (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish):

# Anthropic (required for Claude models)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI (required for GPT/o-series models)
export OPENAI_API_KEY="sk-..."

# Google (required for Gemini models)
export GOOGLE_GENERATIVE_AI_API_KEY="..."

# XAI (required for Grok models)
export XAI_API_KEY="xai-..."

# OpenCode (required for Gemini via OpenCode)
export OPENCODE_API_KEY="..."

After adding, reload your shell:

source ~/.bashrc  # or ~/.zshrc

Security note: The extension stores environment variable names in auth.json, not the actual keys. The file is written with 0600 permissions (owner read/write only).

How It Works

Extension Lifecycle

Startup: When pi loads, the extension's activate() function runs. It reads ~/.pi/agent/models.json and calls pi.registerProvider() for each saved provider, making them immediately available.
/setup command: The registered command launches the interactive wizard. All changes are persisted to disk and registered in the current session.
Session registration: Providers are registered via pi's registerProvider() API with the correct baseUrl, apiKey env var reference, api type, and model definitions.

Standalone Script

The setup.sh script is independent of pi. It:

Detects or creates ~/.pi/agent/
Reads existing config to preserve custom entries
Walks through provider and model configuration interactively
Writes models.json and auth.json

Release Notes

See RELEASE_NOTES.md for version history.

Testing

Since this is an alpha release, we need your help testing. See TESTER_NOTES.md and CONTRIBUTING.md for detailed testing instructions.

Quick Test

# 1. Install the extension (npm)
pi install npm:pi-setup

# 2. Run the standalone wizard to create an initial provider
#    (clone the repo if you don't have the shell script locally yet)
./pi-setup
#    - Add a provider (e.g., Anthropic)
#    - Enter base URL: https://api.anthropic.com
#    - Select API: anthropic-messages
#    - Enter API key (stored in ~/.pi/agent/auth.json)
#    - Add models
#    - Select default model and thinking level

# 3. Start pi
pi

# 4. Verify providers registered
#    The extension should show notifications as providers load

# 5. Test /setup for later edits
/setup

# 6. Test default model selection
#    Re-run /setup and select a default model

# 7. Test thinking level
#    Re-run /setup and change thinking level

Test Matrix

Test Case	Steps	Expected Result
Fresh install	Delete `~/.pi/agent/models.json`, run `./pi-setup`	Wizard creates config before pi starts
Add provider	Menu > Add new provider	Provider saved to models.json
Edit provider	Menu > Edit: anthropic	Existing values shown, saves changes
Edit base URL	Edit provider > Base URL	Input pre-filled with current URL, saves changes
Edit API type	Edit provider > API type	Select from API types, saves changes
Edit API key	Edit provider > API key	Input pre-filled with current key, saves changes
Remove provider	Menu > Edit: anthropic > Remove	Provider deleted from models.json
Add model	Edit provider > Add model	Model added to provider
Remove model	Edit provider > Remove model	Model removed from provider
Set default	Complete wizard, select default model	settings.json updated
Thinking level	Complete wizard, change thinking level	settings.json updated
Auth security	Check `~/.pi/agent/auth.json` permissions	Permissions are `0600`
Duplicate model	Add model with existing ID	Error message, no duplicate created
Missing dir	Delete `~/.pi/agent/`, run setup	Directory structure created
Shell script	Run `./pi-setup` (or `./setup.sh`) standalone	Config files created correctly
Provider persistence	Exit and restart pi, check provider list	Previously saved providers appear
All API types	Add providers for each API type	Correct `api` field values saved

Contributing

See CONTRIBUTING.md for development setup, testing directions, and contribution guidelines.

License

BSD 3-Clause License. See LICENSE for details.

Acknowledgments

pi by Mario Zechner — the coding harness this extends
Built with TypeScript and pi's extension API

☁️ Cloud Credits

Power your AI projects with Ozore.com — use code lundrog50 for 50% off your first month.

direct-pin and custom-router are available on Pro and Max plans only.

☕ Support

If this project helped you, consider buying me a coffee:

Navigation Menu

Repository files navigation

pi-setup

Table of Contents

Features

Dashboard

Installation

Option 1: npm package (recommended)

Option 2: Clone the Repo (development / shell-script-only)

Prerequisites

Usage

Extension Mode

What Happens Behind the Scenes

Shell Script Mode

Configuration Reference

Config Files

Provider Schema

Model Schema

Settings Schema

Supported Providers

API Keys

How It Works

Extension Lifecycle

Standalone Script

Release Notes

Testing

Quick Test

Test Matrix

Contributing

License

Acknowledgments

☁️ Cloud Credits

☕ Support

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
.github		.github
extensions		extensions
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
TESTER_NOTES.md		TESTER_NOTES.md
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
pi-setup		pi-setup
setup.sh		setup.sh
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

pi-setup

Table of Contents

Features

Dashboard

Installation

Option 1: npm package (recommended)

Option 2: Clone the Repo (development / shell-script-only)

Prerequisites

Usage

Extension Mode

What Happens Behind the Scenes

Shell Script Mode

Configuration Reference

Config Files

Provider Schema

Model Schema

Settings Schema

Supported Providers

API Keys

How It Works

Extension Lifecycle

Standalone Script

Release Notes

Testing

Quick Test

Test Matrix

Contributing

License

Acknowledgments

☁️ Cloud Credits

☕ Support

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages