# ๐ฐ๏ธ Pi Extensions
### Supercharge your [pi](https://github.com/earendil-works/pi-mono) coding agent with a Claude Code-style usage panel and multi-skill loader.
[](https://www.npmjs.com/package/@zaganjade/pi-usage)
[](https://www.npmjs.com/package/@zaganjade/pi-multi-skill)
[](https://opensource.org/licenses/MIT)
[](https://pi.dev/packages)
---
## ๐ Install
Pi extensions **must be registered with `pi install`**. Plain `npm install` only downloads files โ pi will not load them unless they appear under `"packages"` in `~/.pi/agent/settings.json`.
### Step 1 โ Install from npm (recommended)
```bash
pi install npm:@zaganjade/pi-usage
pi install npm:@zaganjade/pi-multi-skill
pi install npm:@zaganjade/pi-context
```
### Step 2 โ Reload pi
Inside pi, run:
```
/reload
```
Or restart the pi CLI.
### Step 3 โ Verify
```bash
pi list
```
You should see both packages with install paths. Then open pi and type `/` โ `/usage` and `/skills` should appear in slash autocomplete.
### Other install methods
**GitHub (whole monorepo):**
```bash
pi install git:github.com/ZaganJade/pi-extension
/reload
```
**Local path (development):**
```bash
git clone https://github.com/ZaganJade/pi-extension.git
cd pi-extension
pi install ./usage
pi install ./multi-skill
/reload
```
**Try without saving to settings:**
```bash
pi -e npm:@zaganjade/pi-usage
pi -e npm:@zaganjade/pi-multi-skill
```
### โ ๏ธ Common mistakes
| What people try | Why it fails |
|-----------------|--------------|
| `npm install -g @zaganjade/pi-usage` | Package lands in npm's folder; pi never registers it |
| Adding `npm:...` to `"extensions"` in settings | Wrong key โ npm packages belong in `"packages"` |
| Install but forget `/reload` | Extension not loaded until reload or restart |
| Extension disabled in `pi config` | Re-enable the extension resource for that package |
> No build step โ pi loads TypeScript directly via jiti.
Per-extension docs: [usage/README.md](./usage/README.md) ยท [multi-skill/README.md](./multi-skill/README.md) ยท [Pi-Context/README.md](./Pi-Context/README.md)
---
## ๐ง How it works (pi package system)
This repo is a **monorepo of two independent [pi packages](https://pi.dev/packages)**. Each package ships its own `package.json` with a `pi.extensions` manifest. Pi's package manager reads that manifest, installs the tarball to `~/.pi/agent/npm/`, and loads the declared entry points at startup.
```mermaid
flowchart LR
subgraph install ["Install"]
A["pi install npm:@zaganjade/pi-usage"]
B["pi install npm:@zaganjade/pi-multi-skill"]
end
subgraph settings ["~/.pi/agent/settings.json"]
C["packages[]"]
end
subgraph disk ["~/.pi/agent/npm/node_modules/"]
D["@zaganjade/pi-usage"]
E["@zaganjade/pi-multi-skill"]
end
subgraph runtime ["Pi CLI at runtime"]
F["Resource loader"]
G["Extension runner"]
H["/usage ยท /skills commands"]
end
A --> C
B --> C
C --> D
C --> E
D --> F
E --> F
F --> G
G --> H
```
| Mechanism | Settings key | What it loads |
|-----------|--------------|---------------|
| `pi install npm:...` | `"packages"` | npm/git packages with `pi` manifest |
| Local path in settings | `"extensions"` | Folder or file on disk (dev workflow) |
| Auto-discovery | โ | `~/.pi/agent/extensions/` |
Both extensions are **standalone npm packages** โ install one or both. They do not depend on each other.
---
## ๐ฆ What's inside
| Extension | npm | One-liner |
|-----------|-----|-----------|
| **๐ pi-usage** | [`@zaganjade/pi-usage`](https://www.npmjs.com/package/@zaganjade/pi-usage) | Claude Code-style `/usage` dashboard โ Pi-chan navigation, quota bars, attribution, Wrapped AI year-in-review |
| **โก pi-multi-skill** | [`@zaganjade/pi-multi-skill`](https://www.npmjs.com/package/@zaganjade/pi-multi-skill) | Chain skills via `/skills` โ bundles, load modes, BMAD `--auto`, universal discovery |
| **โ pi-context** | [`@zaganjade/pi-context`](https://www.npmjs.com/package/@zaganjade/pi-context) | Live `/context` window tracker โ category breakdown, dot grid, cross-model handoff (GLM โ GPT) |
---
## ๐ pi-usage
Real-time usage dashboard for pi. Mirrors Claude Code's `/usage` screen but works with **any provider** โ ZAI, OpenAI Codex, OpenRouter, Anthropic, custom routers, and more. The panel includes **Pi-chan**, a lightweight mascot that guides navigation and appears in the Wrapped AI year-in-review.
### Preview โ Overview (`/usage`)
Seven views via `Tab` or `1`โ`7`. A **two-row menu** shows icon tabs plus Pi-chan with a contextual hint. Overview shows always-on quota bars, headline stats, active provider, top consumer, a 30-day trend sparkline, and compact top models.
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Usage โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 5H โ DAY โ WEEK โ ALL
โญโ views โ1 Overview โ โ2 Models โ โฆ โ โฆ7 Wrapped โโโโโโโโโโฎ
(โโฟโ) Pi-chan Quota bars & headline statsโฆ Tab ยท 1-7 jump
Showing: last 24 hours last activity 2m ago ยท 254 sessions
5-hour quota โโโโโโโโโโโโโโโโ 12% used / 145.9M ยท 88% left
โ51.8M โ3.7M โก97.7M 145.9M tokens ยท 855 turns
Top consumer
73% of usage came from model glm-5.2
โ Tab or 1-7 to explore ยท โฆ7 opens Wrapped AI
```
### Preview โ Models view (`/usage-models`)
Full breakdown: model table with tok/s, Skills, **Bundles** (`@debug`, `@bmad-planning`, โฆ), Plugin usage, **Tools** (glyph + bar per tool), and Projects. Multi-skill chains from **pi-multi-skill** attribute every skill and bundle separately.
```
Models % tokens tok/s
glm-5.2 73% โโโโโโโโโโโโโโโ 106.5M 142/s
Skills % tokens
systematic-debugging 18% โโโโโโโโโโโโโโโ 25.4M
frontend-design 12% โโโโโโโโโโโโโโโ 16.1M
Bundles % tokens
@debug 22% โโโโโโโโโโโโโโโ 31.1M
@cc-feature 15% โโโโโโโโโโโโโโโ 21.0M
โ Pi-chan tracked these tool calls
Tools % tokens
โณ read 34% โโโโโโโโโโโโโโโ 48.2M
$ bash 22% โโโโโโโโโโโโโโโ 31.1M
```
### Preview โ Wrapped AI (`/usage-wrapped`)
Year-in-review with report-style sections, Stats-style **monthly heatmap**, rankings, and a Pi-chan footer caption. Mascot pose reacts to streaks and peak hours.
```
Wrapped 2025 โ [ ] โธ ยท y โโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โง๏ผฟโง โ 145.9M tokens ยท 855 turns ยท 89 active days
(โโฟโ)โ Highlights โโ Monthly heatmap โโ Rankings
Monthly activity
tokens by month
โโโ โโโ
Jan Feb Mar โฆ Dec
Less ยทโชโฉโ More ยท Peak month Mar 48.2M
(โงโกโฆ) โ Pi-chan 73% of usage on glm-5.2.
```
### Features
- **Pi-chan navigation** โ two-row menu with icon tabs, per-view hints, and mascot accents in Wrapped AI
- **Live upstream quota** โ 5H/weekly bars from ZAI and OpenAI Codex using pi's own credentials
- **Rate-limit windows** โ captures provider HTTP headers on every response with live reset countdowns
- **Full attribution** โ breakdown by model, skill, **bundle**, plugin, tool (with glyphs), and project
- **Multi-skill aware** โ every skill and `@bundle` in a `/skills` chain counted separately (pairs with pi-multi-skill)
- **Seven TUI views** โ Overview, Models, Daily, Stats, Hourly, Agents, Wrapped AI
- **Wrapped AI** โ professional year-in-review layout with Pi-chan sidebar and data-driven footer caption
- **Adaptive units** โ USD for priced providers, tokens for token-priced providers (ZAI/GLM)
- **Incremental cache** โ session scan cached to `~/.pi/agent/usage-cache.json` (v4, multi-skill + bundle safe)
- **Always-on widget** โ optional compact spend line above the editor (`/usage-widget`)
### Commands
| Command | Description |
|---------|-------------|
| `/usage` | Open the interactive usage panel |
| `/usage-models` ยท `/usage-daily` ยท `/usage-stats` ยท `/usage-wrapped` ยท โฆ | Jump directly to a specific view |
| `/usage-config` | Set 5H/weekly USD & token budgets |
| `/usage-pricing` | Set manual per-model prices for token-priced providers |
| `/usage-widget` | Toggle compact always-on spend widget |
**Latest (v1.9.0):** Pi-chan two-row navigation ยท Wrapped AI report layout ยท monthly heatmap ยท Tools glyphs ยท bundle attribution ยท cache v4 with legacy turn normalization.
### Provider quota
| Provider | Source |
|----------|--------|
| **ZAI (GLM plans)** | `api.z.ai` subscription quota API |
| **OpenAI Codex** | Live rate-limit headers from pi's Codex requests |
| **OpenRouter** | `/api/v1/credits` |
| **OpenAI (metered)** | `/v1/organization/costs` |
| **Any provider** | `after_provider_response` rate-limit headers |
---
## โก pi-multi-skill
Pi's built-in `/skill:name` loads one skill at a time. **pi-multi-skill** (v1.3.0) chains multiple skills in one command with bundles, load modes, BMAD auto-routing, conflict resolution, parallel dispatch, activation stats, and Claude Code-style orchestration.
Full reference: [multi-skill/README.md](./multi-skill/README.md)
### Usage
```
/skills frontend-design,motion-design Create an animated landing page
/skills @bmad-planning --meta Buat PRD untuk fitur X
/skills bmad-master /workflow-status
/skills @bmad-planning --auto
/skills @cc-feature --parallel Build API | Write tests
/skills-stats โ activation statistics
/skills-last --meta โ repeat last activation
/skills-setup โ bundle prerequisites + install guide
/skills โ show help + list skills & bundles
```
### Commands
| Command | Description |
|---------|-------------|
| `/skills` | Chain skills/bundles with load modes, passthrough, `--auto`, `--parallel` |
| `/skills-stats` | Activation stats (modes, bundles, recent history) |
| `/skills-last` | Repeat last `/skills` invocation (optional flag override) |
| `/skills-setup` | Bundle readiness report + BMAD/Superpowers install hints |
### What's new in v1.3.0
| Feature | Description |
|---------|-------------|
| **`/skills-last`** | Replay last activation; override with `--meta` / `--lazy` / `--full` / `--parallel` |
| **BMAD status pre-inject** | `` block for `/workflow-status`, `--auto`, and `bmad-master` |
| **Bundle attribution** | `bundles="@name"` on `` โ tracked in pi-usage **Bundles** section |
| **`/skills-setup`** | On-machine bundle coverage + install guide for BMAD/Superpowers/custom bundles |
### What's new in v1.2.0
| Category | Features |
|----------|----------|
| **Conflicts** | `conflicts_with` frontmatter โ auto-skip conflicting skills with notification |
| **Token budget** | Per-skill `token_budget` override within a bundle load mode |
| **Parallel** | `` JSON template for `pi-subagents`; pipe-separated tasks |
| **Stats** | `/skills-stats` + `~/.pi/agent/multi-skill-stats.json` activation tracking |
| **Bundles** | YAML config (`skill-bundles.yaml`) alongside JSON |
### v1.1.0 highlights
| Category | Features |
|----------|----------|
| **Bundles** | `@bmad-planning`, `@bmad-solutioning`, `@bmad-build`, `@cc-feature`, `@debug` + custom JSON config |
| **Load modes** | `--meta` (minimal tokens), `--lazy` (on-demand refs), `--full` (default) |
| **Orchestration** | Smart ordering (process โ planning โ impl), deduplication, `` wrapper |
| **BMAD** | `--auto` reads workflow status and loads phase-appropriate skills |
| **Commands** | Passthrough: `/skills bmad-master /workflow-status` |
| **Discovery** | Pi commands + settings paths + **Claude plugin cache** + Cursor skills |
| **Session** | Bundle suggestions after user turns; `skill-index.json` rebuilt each session |
| **Usage** | Multi-skill attribution โ all skills counted in `pi-usage` `/usage-models` |
### All features
- **Parallel dispatch** โ `--parallel Task A | Task B` with structured subagent template
- **Conflict resolution** โ `conflicts_with` frontmatter deduplication
- **Activation stats** โ `/skills-stats` tracks modes, bundles, recent history
- **YAML bundles** โ `skill-bundles.yaml` alongside JSON config
- **Skill bundles** โ `@name` expands to curated skill sets; merge with `~/.pi/agent/skill-bundles.json`
- **Load modes** โ control token cost per activation
- **Smart ordering** โ process skills first, then planning, then implementation
- **Command passthrough** โ embed `/workflow-status`, `/dev-story`, etc.
- **BMAD `--auto`** โ phase detection from `docs/bmm-workflow-status.yaml`
- **Universal discovery** โ finds Superpowers skills in Claude plugin cache even if not in pi `"skills"` paths
- **Autocomplete** โ skills and bundles with descriptions; comma-chaining support
- **Legacy formats** โ `/skills:name1,name2` and `/skill:name1+name2`
- **Parallel hint** โ `--parallel` with pipe-separated tasks; JSON template when `pi-subagents` installed
- **pi-usage integration** โ every skill and `@bundle` in a chain attributed separately in `/usage-models`
---
## ๐ Latest releases
| Package | Version | Highlights |
|---------|---------|------------|
| `@zaganjade/pi-usage` | **1.9.0** | Pi-chan menu ยท Wrapped report ยท monthly heatmap ยท Tools glyphs ยท bundle breakdown ยท cache v4 |
| `@zaganjade/pi-multi-skill` | **1.3.0** | `/skills-last` ยท `/skills-setup` ยท BMAD status inject ยท bundle attribution for usage |
| `@zaganjade/pi-context` | **0.2.0** | Claude Codeโstyle context panel ยท scannable table ยท compact grid |
---
## ๐๏ธ Architecture
Monorepo layout:
```
pi-extension/
โโโ usage/ โ @zaganjade/pi-usage
โ โโโ src/
โ โโโ index.ts orchestrator โ commands, events, scan + quota coordination
โ โโโ view.ts TUI panel (UsageView, 7 views, Pi-chan menu)
โ โโโ mascot.ts Pi-chan art, view icons, tool glyphs
โ โโโ aggregate.ts session scan, attribution, multi-skill windowing
โ โโโ provider.ts live quota fetch + rate-limit parsing
โ โโโ config.ts ~/.pi/agent/usage.json
โ โโโ cache.ts ~/.pi/agent/usage-cache.json
โ โโโ prices.ts bundled default model prices
โ โโโ format.ts token / currency / bar helpers
โโโ multi-skill/ โ @zaganjade/pi-multi-skill
โโโ src/
โโโ index.ts /skills, /skills-stats, events, orchestration
โโโ discover.ts universal skill discovery
โโโ bundles.ts preset + user bundle loading (JSON/YAML)
โโโ metadata.ts frontmatter, priority sorting
โโโ build.ts message builder, load modes, parallel dispatch
โโโ conflicts.ts conflicts_with resolution
โโโ subagents.ts pi-subagents detection + dispatch template
โโโ stats.ts activation tracking
โโโ yaml-bundles.ts YAML bundle parser
โโโ bmad-auto.ts BMAD phase auto-routing
โโโ bmad-status.ts BMAD workflow status pre-inject
โโโ bundle-status.ts bundle readiness + /skills-setup report
โโโ completions.ts slash autocomplete for skills & commands
โโโ parse-args.ts flags & embedded commands
โโโ registry.ts skill-index.json
โโโ suggestions.ts context-aware hints
โโโ types.ts shared types
โโโ Pi-Context/ โ @zaganjade/pi-context
โโโ src/
โโโ index.ts /context, handoff commands, events, widget
โโโ snapshot.ts live category snapshot from session + prompt
โโโ estimate.ts per-category token estimation
โโโ view.ts ContextView TUI (bar + grid + list)
โโโ handoff.ts export/import/scale Context Pack
โโโ config.ts ~/.pi/agent/context.json
โโโ mascot.ts Context-chan hints
```
### pi-usage data flow
Opening `/usage` runs **two independent pipelines in parallel** โ session history (historical attribution) and provider quota (live upstream state). They merge only at render time inside `UsageView`.
```mermaid
flowchart TB
subgraph trigger ["Trigger"]
CMD["/usage or /usage-*"]
end
subgraph sessionTrack ["Track A โ Session aggregation (historical)"]
direction TB
S1["~/.pi/agent/sessions/*.jsonl"]
S2["usage-cache.json\nmtime-keyed per file"]
S3["usage.json\nbudgets ยท excludes ยท modelPrices"]
S4["prices.ts\nbundled defaults"]
AGG["aggregate.ts\nscanSessions()"]
MAPS["buildAttributionMaps()\ntool/skill โ plugin"]
REPORT["Report\nall attributed turns"]
WIN["windowize()\n5h ยท 24h ยท 7d ยท all"]
S1 --> AGG
S2 --> AGG
S3 --> AGG
S4 --> S3
MAPS --> AGG
AGG --> REPORT
REPORT --> WIN
end
subgraph providerTrack ["Track B โ Live provider quota"]
direction TB
P1["ctx.model\nactive provider"]
P2["after_provider_response\nrate-limit headers"]
P3["Provider APIs\nZAI ยท Codex ยท OpenRouter ยท OpenAI"]
PROV["provider.ts\nfetchProviderQuota()"]
QUOTA["ProviderQuota\nplan % ยท resets ยท credits"]
P1 --> PROV
P2 --> PROV
P3 --> PROV
PROV --> QUOTA
end
subgraph render ["Render"]
IDX["index.ts\nopenUsagePanel()"]
VIEW["view.ts\nUsageView"]
CMD --> IDX
IDX --> AGG
IDX --> PROV
WIN --> VIEW
QUOTA --> VIEW
end
subgraph persist ["Persistence"]
CACHE_W["cache.ts\nsaveScanCache()"]
AGG --> CACHE_W
CACHE_W --> S2
end
```
**Step-by-step when `/usage` opens:**
| Step | Module | What happens |
|------|--------|--------------|
| 1 | `index.ts` | Creates `UsageView`, binds TUI, kicks off scan + quota fetch |
| 2a | `cache.ts` | Loads `usage-cache.json`; skips unchanged session files (mtime + size) |
| 2b | `aggregate.ts` | Parses new/changed JSONL โ attributes each turn to model, project, skill, plugin, tool |
| 2c | `config.ts` + `prices.ts` | Applies budgets, excludes, and manual/bundled model prices at parse time |
| 3 | `provider.ts` | Fetches upstream quota (ZAI plan %, Codex headers, etc.) + merges captured rate limits |
| 4 | `view.ts` | `windowize()` slices `Report` by selected window; renders Overview / Models / โฆ / Wrapped |
| 5 | `cache.ts` | Writes updated scan cache back to disk |
**Background events (outside the panel):**
| Event | Effect |
|-------|--------|
| `session_start` | Rebuild `AttributionMaps` from `pi.getAllTools()` / `pi.getCommands()` |
| `after_provider_response` | Capture rate-limit headers for next quota refresh |
| `model_select` | Update active provider; refresh spend widget |
| `turn_end` | Refresh always-on widget from current session branch |
**Attribution model:** skills, plugins, tools, and models are *independent characteristics* โ one turn can count toward several buckets (like Claude Code). Percentages across categories do not sum to 100%.
### pi-multi-skill flow
```mermaid
flowchart LR
CMD["/skills @bundle --meta /cmd"]
PARSE["parse-args + bundles"]
DISC["discover.ts"]
ORDER["metadata sort"]
BUILD["build.ts\nmeta/lazy/full"]
SEND["sendUserMessage()\nmanually_attached_skills"]
CMD --> PARSE --> DISC --> ORDER --> BUILD --> SEND
```
### Extension API surface
Both packages are standard pi extensions โ a default-export factory receiving `ExtensionAPI`:
| API used | pi-usage | pi-multi-skill |
|----------|----------|----------------|
| `pi.registerCommand()` | `/usage`, `/usage-*`, `/usage-config`, โฆ | `/skills`, `/skills-stats`, `/skills-last`, `/skills-setup` |
| `pi.on("session_start")` | rebuild attribution maps | clear cache + skill index |
| `pi.on("after_provider_response")` | capture rate-limit headers | โ |
| `pi.on("model_select")` / `turn_end` | refresh spend widget | skill bundle suggestions |
| `pi.on("input")` | โ | legacy `/skills:` / `/skill:+` formats |
| `pi.getCommands()` / `loadSkills()` | tool/plugin attribution | skill discovery (via discover.ts) |
| `pi.sendUserMessage()` | โ | inject combined skills |
| `pi.ui.custom()` / `setWidget()` | panel + always-on widget | โ |
---
## โ๏ธ Configuration (pi-usage)
`~/.pi/agent/usage.json` (auto-created on first `/usage-config`):
```json
{
"fiveHourLimit": 20,
"weeklyLimit": 100,
"fiveHourTokenLimit": 2000000,
"weeklyTokenLimit": 10000000,
"showWidget": false,
"excludeProjects": ["/tmp/throwaway"],
"maxSessions": 1000
}
```
| Key | Description |
|-----|-------------|
| `fiveHourLimit` / `weeklyLimit` | USD budgets for priced providers |
| `fiveHourTokenLimit` / `weeklyTokenLimit` | Token budgets for token-priced providers (ZAI/GLM) |
| `showWidget` | Compact one-line spend summary above the editor |
| `excludeProjects` | Project cwd prefixes to skip during aggregation |
| `maxSessions` | Safety cap on session files to scan |
Full reference: [usage/README.md](./usage/README.md)
---
## ๐ License
MIT โ see [LICENSE](./usage/LICENSE).
**Author:** [ZaganJade](https://github.com/ZaganJade) ยท tipstrik81@gmail.com
[Report a bug](https://github.com/ZaganJade/pi-extension/issues) ยท [Request a feature](https://github.com/ZaganJade/pi-extension/issues) ยท [npm: @zaganjade](https://www.npmjs.com/~zaganjade)