@raingor/pi-web-switch

---

✨ 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
• 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:

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 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
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

# 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 — 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 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 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
Language	TypeScript 5.8
Build	Vite 6
Styling	Tailwind CSS v4
State	Zustand
Charts	Recharts
Icons	Lucide React
Routing	React Router v7

🗂️ 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)
        ├── chat/            # ChatPage (local pi conversation workspace)
        ├── 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)

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	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 (pi sessions) — ?range=today|7d|30d|custom&from=&to=
GET	/api/pi/all-usage-range	Same shape, but combined across all sources (pi + cindy + claude + codex + 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:

{
  "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

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
• Homepage: raingor.github.io/my-blog
• GitHub: github.com/Raingor

📄 License

MIT