---
slug: "raingor-pi-web-switch"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/Raingor/pi-web-switch@main/README.md"
repo: "https://github.com/Raingor/pi-web-switch"
source_file: "README.md"
branch: "main"
---
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** โ Today / 7 days / 30 days / Custom date range selector with auto-refresh (5s/10s/30s/60s)
- **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
### ๐ฌ 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)
- **Enabled Models** โ View and manage the full enabled models list
- **Extensions & Packages** โ Manage pi packages list
- **Import/Export** โ Download full config as JSON, restore from backup
- **Reset** โ Factory reset to blank configuration
## ๐ 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 app ships with definitions for **11 built-in providers** and **26 models** (hardcoded from pi's Rust source):
| Provider | Models |
|----------|--------|
| Anthropic | Claude Sonnet 4, Sonnet 4.5, Opus 4, Haiku 3.5 |
| OpenAI | GPT-4o, GPT-4o-mini, GPT-5.1, o3-mini |
| DeepSeek | DeepSeek V3, DeepSeek R1 |
| OpenCode | DeepSeek V4 Flash (Free), DeepSeek V4 Flash |
| OpenCode Go | DeepSeek V4 Flash, V4 Pro, GLM 5.1, Qwen 3.7 Max, MiMo V2.5 |
| SenseNova | GLM 5.2, DeepSeek V4 Flash |
| Google Gemini | Gemini 2.5 Flash, Gemini 2.5 Pro |
| OpenRouter | Claude Sonnet 4, DeepSeek R1 |
| Mistral | Mistral Large |
| GitHub Copilot | Copilot GPT-4o |
| Groq | Llama 3.3 70B |
## ๐ 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.
## ๐๏ธ 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
โโโ public/
โ โโโ pi.svg
โโโ src/
โโโ main.tsx # Entry point + theme sync + init gate + i18n provider
โโโ App.tsx # Router setup (6 routes)
โโโ index.css # Tailwind + CSS theme variables (light/dark)
โโโ types/index.ts # All TypeScript interfaces
โโโ data/
โ โโโ builtin-providers.ts # Hardcoded built-in provider definitions
โโโ store/
โ โโโ config-store.ts # Zustand store (fetches from /api/pi/*)
โโโ 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
โ โโโ translations/ # Translation files (en, zh-CN, zh-TW, ja)
โโโ components/
โโโ layout/ # AppShell, Sidebar (6 nav items + language switcher)
โโโ ui/ # StatCard, Badge, Modal, EmptyState
โโโ dashboard/ # DashboardPage + charts (hourly/daily granularity)
โโโ models/ # ModelsPage + forms
โโโ providers/ # ProvidersPage + forms
โโโ sessions/ # SessionsPage + MemoryPage
โโโ settings/ # SettingsPage
```
## ๐พ 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) |
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
The Vite dev server exposes these endpoints at `/api/pi/*`:
| 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` | List hardcoded built-in providers |
| GET | `/api/pi/usage` | Aggregated token/cost/request data from sessions |
| GET | `/api/pi/usage-range` | Date-range filtered usage with hourly/daily breakdown |
| GET | `/api/pi/sessions` | Session list grouped by project |
| DELETE | `/api/pi/session?path=` | Delete a session file (path must be under sessions/) |
| GET | `/api/pi/memory` | Read MEMORY.md, USER.md, failures.md |
## ๐ฆ 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-web-switch start` | Launch the dashboard at `http://localhost:5173` |
| `/pi-web-switch stop` | Stop the server |
| `/pi-web-switch status` | Check if the dashboard is running |
### 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
```
## ๐ Links
- **Homepage:** [raingor.github.io/my-blog](https://raingor.github.io/my-blog/)
- **GitHub:** [github.com/Raingor](https://github.com/Raingor)
## ๐ License
MIT