pi-web-switch
Web UI for pi coding agent โ live configuration management, session browser, and memory viewer
๐ฌ๐ง English ยท
๐จ๐ณ ไธญๆ ยท
๐ฏ๐ต ๆฅๆฌ่ช
Inspired by cc-switch โ a visual dashboard for managing your pi coding agent providers, models, token usage, sessions, and settings.
Reads data directly from ~/.pi/agent/ โ no mock data, no database, no backend setup required.
---
## โจ Features
### ๐ Dashboard
- **Usage Statistics** โ All time / Today / 7 days / 30 days / Custom date range selector with auto-refresh (5s/10s/30s/60s)
- **All Sources Overview** โ Combine all locally supported usage sources in one dashboard, while keeping Pi and ChatGPT/Codex views available separately
- **Token Breakdown** โ Exact token count with approximate display (e.g. `1,631,022 โ 1.6M`) and Input/Output/Cache Hit/Cache Create breakdown
- **Cost Tracking** โ Daily cost chart + Provider/Model stats tabs with aggregated data
- **Cache Hit Rate** โ Visual progress bar showing cache efficiency
- **Request Log** โ Detailed log table with time, provider, model, tokens, cost
- **Currency Switch** โ Toggle between USD and CNY with real-time conversion (1 USD = 7.2 CNY)
- **Hourly/Daily Granularity** โ Today view shows per-hour data; 7d/30d views show per-day data
- All data sourced from **real pi session files** (`~/.pi/agent/sessions/*.jsonl`)
### ๐ฆ Models
- **Model Grid** โ Browse all built-in and custom models with search and filter
- **Enable/Disable** โ Toggle models on/off to match your `enabledModels` config
- **Edit Model** โ Update capabilities, cost, context window, max tokens
- **Add Model** โ Create new models for any provider
- **Delete Model** โ Remove custom models
### ๐ Providers
- **Provider List** โ Expandable cards for all built-in and custom providers
- **Custom Providers** โ Add Ollama, vLLM, LM Studio, or any OpenAI-compatible provider
- **API Key Management** โ Set/remove API keys per provider (saved to `auth.json`)
- **Provider Configuration** โ baseUrl, API type, custom headers, auth method
- **Enabled Models Panel** โ Cross-provider list of every enabled model with one-click disable / disable-all, kept in sync with each provider's per-model toggles
- **Fetch Models Online** โ Pull a provider's live model list from its `/models` endpoint and import with one click
### ๐ฌ Sessions
- **Project Grouping** โ Auto-decodes session directory names into project paths
- **Session Browser** โ View all 100+ sessions across projects
- **Session Details** โ Name, timestamp, message count, duration, provider/model used
- **Search & Filter** โ Filter sessions by project name
- **Delete Sessions** โ Remove old session files (sessions updated within 3 days are protected)
### ๐ง Memory (pi-hermes-memory)
- **Project Memories** โ View `MEMORY.md` content with Markdown rendering
- **User Profile** โ Display `USER.md` preferences and settings
- **Failure Records** โ Browse `failures.md` known issues
- **Live Sync** โ Content updates immediately when memory files change on disk
### ๐ Multi-language
- **English** ๐ฌ๐ง โ Default
- **Simplified Chinese** ๐จ๐ณ โ ็ฎไฝไธญๆ
- **Traditional Chinese** ๐ญ๐ฐ โ ็น้ซไธญๆ
- **Japanese** ๐ฏ๐ต โ ๆฅๆฌ่ช
- Language switcher in sidebar footer, persists across sessions
### โ๏ธ Settings
- **Defaults** โ Default provider, model, thinking level, project trust
- **Theme** โ Light / Dark / System with immediate toggle (CSS variables for both modes)
- **Interface Zoom** โ Scale the entire UI by percentage (50%โ200%), plus a font-size slider
- **Extensions & Packages** โ Manage pi packages list
- **Import/Export** โ Download full config as JSON, restore from backup
- **Reset** โ Factory reset to blank configuration
### ๐ฅ๏ธ Native macOS Menu Bar
- **Two Lightweight Apps** โ Separate Swift/AppKit menu bar apps for Pi usage and ChatGPT/Codex usage, with no Electron, WebView, or resident web server
- **Pi Usage App** โ Pi today/7-day usage, cost, cache rate, and provider totals
- **ChatGPT Usage App** โ Local ChatGPT/Codex session usage and official Codex quota
- **Background Refresh** โ Reads local session files and refreshes quota data without blocking the menu bar
- **Separate Visibility Controls** โ The Settings page controls each menu bar app through `~/.pi/agent/settings.json`
macOS and Swift Command Line Tools are required. From a checkout of this repository:
```bash
npm run native:build # Build both .app bundles under release/
npm run native:open # Build and launch both menu bar apps
```
## ๐ Theme Support
Full light and dark mode with system-follow support. Theme toggles instantly via CSS custom properties โ no page reload needed. All components adapt including sidebar, modals, forms, charts, and scrollbars.
## ๐งฑ Built-in Providers
The built-in catalog is read **live from your local pi installation** โ the same data pi ships and [pi.dev/models](https://pi.dev/models) lists (`@earendil-works/pi-ai/dist/providers/data/*.json`). Upgrading pi upgrades this panel; with pi `0.85.1` that is **37 providers and 1,153 models**, 733 of which accept image input. Results are cached for 5 minutes and refreshed when the dev server restarts.
When no pi install can be located (e.g. a fresh checkout), the app falls back to a small hand-maintained catalog in `src/data/builtin-providers.ts` โ 10 providers / 38 models covering Anthropic, OpenAI, DeepSeek, Google, OpenCode Zen (+ Go), OpenRouter, Mistral, GitHub Copilot and Groq.
Models you add or import are written to `~/.pi/agent/models.json` and merged over the catalog: an entry whose id matches a built-in provider (e.g. `mistral`) augments that provider instead of appearing as a duplicate, and a display name you set there wins over the catalog name.
## ๐ Getting Started
### Prerequisites
- **pi coding agent** installed and configured (so `~/.pi/agent/` exists)
- Node.js 18+
### Setup
```bash
# Clone
git clone https://github.com/Raingor/pi-web-switch.git
cd pi-web-switch
# Install dependencies
npm install
# Start dev server (reads ~/.pi/agent/ automatically)
npm run dev
# Build for production
npm run build
# Preview production build
npm run preview
```
The dev server automatically serves pi configuration via Vite middleware at `/api/pi/*` โ no separate backend process needed.
## ๐ฅ๏ธ Sister Project โ pi-of-cindy
pi-web-switch runs in the browser. If you want a more complete **desktop, mobile, and AI agent workbench**, see its sister project:
> **[pi-of-cindy](https://github.com/Raingor/pi-of-cindy)** โ a pi-only rework of the CINDY client, including an Electron desktop app, an Expo / React Native mobile app, and shared packages.
> It uses the local [pi](https://github.com/earendil-works/pi) CLI as its sole workbench, with Pi providers, dashboard, tasks, memory, subagents, and local session import. It shares `~/.pi/agent/` with the local pi CLI.
>
> Key capabilities of pi-of-cindy:
> - **Multi-platform agent workbench** โ desktop, mobile, and shared capabilities in one pnpm monorepo
> - **Harness ร model composition** โ supports Agent Harnesses such as Claude Code and Codex, with planning, parallel execution, and independent review
> - **Real-environment execution** โ can operate browsers, computers, and phones using local files and logged-in apps
> - **Pi-only local workflow** โ imported pi CLI sessions can continue directly, with providers and models kept in sync with the terminal
> - **Apache-2.0 open source** โ build and extend the client yourself
>
> See the **[pi-of-cindy README](https://github.com/Raingor/pi-of-cindy)** for downloads and complete documentation.
**Both share the local `~/.pi/agent/` config**, so providers, models, and memories changed in either project remain available to the other and to the terminal `pi`.
| | pi-web-switch (this project) | pi-of-cindy |
|---|---|---|
| Form | Browser panel (Vite dev server) | Electron desktop app + Expo / React Native mobile app |
| Focus | Configuration management โ Dashboard / Providers / Sessions / Memory side by side | Multi-platform AI agent workbench โ task execution, harness orchestration, and local sessions |
| Pi integration | Pi package / local configuration panel | Local pi CLI as the core, sharing `~/.pi/agent/` |
| License | MIT | Apache-2.0 |
| Development | `npm run dev` | `pnpm install` + `pnpm restart:desktop:remote` |
## ๐๏ธ Tech Stack
| Layer | Technology |
|-------|-----------|
| Framework | [React 19](https://react.dev/) |
| Language | [TypeScript 5.8](https://www.typescriptlang.org/) |
| Build | [Vite 6](https://vitejs.dev/) |
| Styling | [Tailwind CSS v4](https://tailwindcss.com/) |
| State | [Zustand](https://github.com/pmndrs/zustand) |
| Charts | [Recharts](https://recharts.org/) |
| Icons | [Lucide React](https://lucide.dev/) |
| Routing | [React Router v7](https://reactrouter.com/) |
## ๐๏ธ Project Structure
```
pi-web-switch/
โโโ index.html
โโโ package.json
โโโ vite.config.ts # Vite config + pi API plugin (middleware)
โโโ tsconfig.json
โโโ server/
โ โโโ pi-reader.ts # Server-side module: reads ~/.pi/agent/ files + parses sessions
โโโ native/
โ โโโ NativeUsageSupport.swift # Shared usage readers and formatters
โ โโโ PiUsageMenuBar.swift # Pi usage menu bar app
โ โโโ ChatGPTUsageMenuBar.swift # ChatGPT/Codex usage menu bar app
โโโ scripts/
โ โโโ build-native-menubar.sh
โโโ pi-package/
โ โโโ index.ts # Extension entry: /pi-switch and /pi-usage commands
โ โโโ skills/
โโโ public/
โ โโโ pi.svg
โโโ src/
โโโ main.tsx # Entry point + theme sync + init gate + i18n provider
โโโ App.tsx # Router setup
โโโ index.css # Tailwind + CSS theme variables (light/dark)
โโโ types/index.ts # All TypeScript interfaces
โโโ data/
โ โโโ builtin-providers.ts # Static built-in provider fallback catalog
โ โโโ model-catalog.ts # Smart model catalog + metadata autofill
โ โโโ changelog.ts # Version changelog for the "What's new" dialog
โโโ store/
โ โโโ config-store.ts # Zustand store (fetches from /api/pi/*)
โโโ hooks/
โ โโโ useSessionUsage.ts # Live session token/cost polling
โโโ lib/
โ โโโ utils.ts # Formatting helpers (tokens, cost with USD/CNY)
โ โโโ i18n.tsx # Multi-language system (React Context + hook)
โ โโโ currency.ts # Currency switching (USD/CNY toggle)
โ โโโ config.ts # Config import/export helpers
โ โโโ pi-settings.ts # Nested settings merge (keeps sibling CLI values)
โ โโโ models-json.ts # models.json payload builders (keeps disabled providers)
โ โโโ provider-import.ts # Freeform provider/key-pool import parser
โ โโโ translations/ # Translation files (en, zh-CN, zh-TW, ja)
โโโ components/
โโโ layout/ # AppShell, BasicSidebar (nav + language switcher)
โโโ ui/ # StatCard, Badge, Modal, EmptyState
โโโ help/ # HelpButton, ChangelogButton
โโโ dashboard/ # DashboardPage + charts (hourly/daily granularity)
โโโ generate/ # GeneratePage (image / video generation)
โโโ providers/ # ProvidersModelsPage + forms
โโโ speedtest/ # ModelSpeedTestPage
โโโ subagents/ # SubagentsPage (agents, chains, run history)
โโโ sessions/ # SessionsPage + MemoryPage
โโโ settings/ # SettingsPage, PiCliSettingsPage, SkillsPage, CommandsPage
```
## ๐พ Data Source
All data is read directly from **`~/.pi/agent/`** on your machine via a Vite middleware API plugin โ no mock data, no database, no external service.
| File | Purpose |
|------|---------|
| `~/.pi/agent/settings.json` | Default provider, model, theme, enabled models, packages |
| `~/.pi/agent/auth.json` | API keys per provider |
| `~/.pi/agent/models.json` | Custom provider definitions (baseUrl, API type, models) |
| `~/.pi/agent/sessions/*.jsonl` | Session history with token usage, model, provider per message |
| `~/.pi/agent/pi-hermes-memory/*.md` | Hermes memory (MEMORY.md, USER.md, failures.md) |
| local pi install (`@earendil-works/pi-ai`) | Built-in provider & model catalog โ read-only |
Changes made in the UI are written back to these files in real time โ the pi agent picks them up on next reload.
### Sessions & Usage
- The app parses **106+ JSONL session files** from `sessions/` directory
- Each assistant message's API usage data (tokens, cost) is extracted and aggregated
- Dashboard shows real token consumption, costs, and request volumes across all sessions
- Sessions list groups by project (decoded from directory names) with 24+ project groups
## ๐งฉ API Routes
These endpoints at `/api/pi/*` are served by the Vite middleware, so the frontend talks to your local pi install with no separate backend process:
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/pi/settings` | Read `settings.json` |
| POST | `/api/pi/settings` | Write `settings.json` |
| GET | `/api/pi/auth` | Read `auth.json` |
| POST | `/api/pi/auth` | Write `auth.json` |
| GET | `/api/pi/models` | Read `models.json` |
| POST | `/api/pi/models` | Write `models.json` |
| GET | `/api/pi/builtin-providers` | Built-in provider + model catalog, read from the local pi install (static fallback if absent) |
| GET | `/api/pi/usage` | Aggregated token/cost/request data from sessions |
| GET | `/api/pi/usage-range` | Date-range filtered usage (pi sessions) โ `?range=all\|today\|7d\|30d\|custom&from=&to=` |
| GET | `/api/pi/all-usage-range` | Same shape, but combined across **all** local sources (pi + cindy + claude + codex + ChatGPT/Codex Desktop + atomcode + copilot) |
| GET | `/api/pi/{cindy-pi\|claude\|codex\|opencode\|gemini\|grok\|atomcode\|copilot}-usage-range` | Per-source usage range |
| GET | `/api/pi/copilot-usage-range` | Local Copilot CLI usage from `~/.copilot/session-store.db` (tokens / requests per day per model; no GitHub API or token required) |
| GET | `/api/pi/copilot-config` | Read Copilot GitHub config (username, token) |
| POST | `/api/pi/copilot-config` | Write Copilot GitHub config |
| GET | `/api/pi/sessions` | Session list grouped by project |
| DELETE | `/api/pi/session?path=` | Move a session file to trash (path must be under sessions/) |
| POST | `/api/pi/session/trash` | Move a session to trash (body: `{ path }`) |
| POST | `/api/pi/session/restore` | Restore a session from trash (body: `{ trashPath }`) |
| GET | `/api/pi/session-preview` | Preview session messages โ `?path=` |
| GET | `/api/pi/trash` | List trashed sessions |
| DELETE | `/api/pi/trash?path=` | Permanently delete a trashed session |
| GET | `/api/pi/memory` | Read MEMORY.md, USER.md, failures.md |
| POST | `/api/pi/memory/delete-entry` | Delete a memory entry (body: `{ filename, text }`) |
| GET | `/api/pi/subagents` | Read subagent run history |
| GET | `/api/pi/check-updates` | Check pi package updates |
| POST | `/api/pi/apply-updates` | Apply package updates (body: `{ names }`) |
| POST | `/api/pi/provider-test` | Test a provider connection (body: `{ baseUrl, apiKey }`) |
| POST | `/api/pi/provider-models` | Fetch a provider's live model list (body: `{ baseUrl, apiKey, providerId }`) |
| POST | `/api/pi/model-test` | Test a model (body: `{ baseUrl, modelId, apiKey, apiType }`) |
All `-usage-range` endpoints accept `&refresh=1` to force a rescan, bypassing the 30-second session cache (the Dashboard refresh button sends this).
## ๐ฆ Pi Package
pi-web-switch can be installed as a **pi coding agent extension**, allowing you to start/stop the dashboard directly from your pi session.
### Install
Add `npm:pi-web-switch` to your `~/.pi/agent/settings.json` packages list:
```json
{
"packages": ["npm:pi-web-switch"]
}
```
Or use the Settings page in the dashboard to add it.
### Commands
Once installed, the following commands are available in your pi session:
| Command | Description |
|---------|-------------|
| `/pi-switch start` | Launch the dashboard at `http://localhost:5173` |
| `/pi-switch stop` | Stop the server |
| `/pi-switch status` | Check if the dashboard is running |
| `/pi-usage` | Print a quick usage summary (today + 7 days) in the terminal โ tokens / cost / requests / daily sparkline, without launching the dashboard |
The `/pi-usage` command reads `~/.pi/agent/sessions/*.jsonl` directly and aggregates today + last-7-days stats, so you can see your usage at a glance from any pi session.
### Package Structure
```
pi-web-switch/
โโโ package.json # npm package with pi.extensions + pi.skills
โโโ pi-package/
โ โโโ index.ts # Extension entry: registers /pi-web-switch command
โ โโโ skills/
โ โโโ pi-web-switch/
โ โโโ SKILL.md # Usage documentation
โโโ server/
โ โโโ pi-reader.ts # Server-side: reads ~/.pi/agent/ files
โโโ src/ # React frontend
```
## ๐ฌ Community
Join the **Telegram group** for questions, suggestions, and bug reports:
๐ **[Join the pi-web-switch Telegram group](https://t.me/+ODpy7_7NlOE4NzA1)**
When reporting an issue, please include:
1. Your OS (macOS / Windows / Linux)
2. Your version โ `npm view @raingor/pi-web-switch version`
3. A clear description plus any error screenshots or logs
## ๐ Links
- **Sister project (CINDY pi-only client):** [github.com/Raingor/pi-of-cindy](https://github.com/Raingor/pi-of-cindy)
- **Homepage:** [raingor.github.io/my-blog](https://raingor.github.io/my-blog/)
- **GitHub:** [github.com/Raingor](https://github.com/Raingor)
## ๐ License
MIT