pi-usage-dashboard

A feature-rich usage dashboard footer for Pi coding agent 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)

pi install npm:pi-usage-dashboard

From GitHub

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

Local

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

Or just symlink it:

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)