# pi-usage-dashboard

A feature-rich usage dashboard footer for [Pi coding agent](https://pi.dev) that shows live session stats directly in the chat interface.

## What it shows

```
(main) • my-session                                     ⏱ 12m 34s  ● ~/Worktrees
Turns 5 ⏱ 2.3s │ Reqs 5 │ Tokens ↑25k ↓1.8k │ Cost $0.04 │ Ctx ████░░ 45k/128k (35.2%) │ $ $0.04/$10.00 (0%) $9.96   🧠◐ portkey/deepseek-v4-pro/2024-05-01-preview
⚙ Running: bash (tool 3 this turn)  MCP: 0/3 servers
```

### Line 1 — Session metadata
- **Git branch** and **session name**
- **Active tools count** and **skills loaded** (`[8 tools, 3 skills]`)
- **Session elapsed time** (`⏱ 12m 34s`)
- **Activity indicator**: `●` while streaming, `⚙ toolname` while executing
- **Working directory**
- **`[compacted]`** warning if context was auto-compacted

### Line 2 — Stats bar
| Metric | Description | Color warnings |
|--------|-------------|----------------|
| **Turns** | Conversation turns this session | Yellow at 20+ |
| **⏱ latency** | Response time from prompt to first token | Yellow at 10s+ |
| **Reqs** | Total LLM API requests | Warning at 50+, error at 100+ |
| **Tokens** ↑↓ | Input/output tokens | Warning at 200k+, error at 500k+ |
| **Cost** | Estimated session cost (USD) | Warning at $2+, error at $5+ |
| **Ctx** ████░░ | Live context window usage bar + numbers | Green → yellow → red |
| **$ Budget** | Budget spend with progress bar | Green → yellow → red |
| **🧠 Thinking** | Thinking level indicator (○ ◐ ◑ ◕ ● ⬤) | Yellow when active |
| **Model** | `provider/model-id` | Accent colored |

### Line 3 — Live activity
- `● Streaming response...` while generating
- `⚙ Running: <tool> (tool N this turn)` during tool execution
- Extension statuses from other installed extensions

## Commands

| Command | Description |
|---------|-------------|
| `/usage` | Full-screen overlay with detailed breakdown |
| `/budget 5.00` | Set a budget limit in USD |
| `/toggledash` | Show/hide the dashboard footer |

## LLM Tools

The extension registers these tools that the agent can call:

| Tool | Description |
|------|-------------|
| `show_usage_stats` | Return session usage, tokens, cost, budget |
| `register_usage_budget` | Set budget with `assigned` + `spent_so_far` params |
| `fetch_budget_from_portkey` | Prompt agent to fetch real spend from Portkey MCP |

## Budget Tracking

1. **Auto-fetch**: On startup, reads your Portkey API key from `~/.pi/agent/models.json` and fetches month-to-date cost, then sets budget = 2× current spend
2. **Manual**: `/budget 10.00`
3. **Agent-driven**: The LLM calls `register_usage_budget` after fetching from Portkey MCP
4. **Persistent**: Budget survives session restarts

## Install

### From npm (recommended)

```bash
pi install npm:pi-usage-dashboard
```

### From GitHub

```bash
pi install git:github.com/jay-rathod/pi-usage-dashboard
```

### Local

```bash
pi install ./path/to/pi-usage-dashboard
```

Or just symlink it:

```bash
ln -s /path/to/pi-usage-dashboard/index.ts ~/.pi/agent/extensions/usage-dashboard.ts
```

## Configuration

No configuration needed — works out of the box. The footer replaces Pi's default footer automatically.

To toggle the dashboard: `/toggledash`

## Requirements

- Pi coding agent (latest)
- Portkey API key in `models.json` (for auto-budget fetching only; manual `/budget` works without it)