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)