@pi/agent-extensions-pi-usages

Pi usages extension — Enhanced quota tracking with persistent overlay and multi-provider support.

Overview

pi-usages is a Pi extension that replaces and improves upon @porche/pi-usage. It provides real-time quota tracking, persistent on-screen quota indicators, and support for multiple AI providers.

Key Features

• ✅ Persistent Quota Overlay — Single-row belowEditor widget showing active provider's quota at a glance
• ✅ Real-time Refresh — Auto-updates every 10 min of agent activity + manual refresh with /usage refresh
• ✅ Multi-Provider Support — Anthropic, GitHub Copilot, OpenAI Codex, OpenRouter, Ollama Cloud
• ✅ GitHub Copilot Fixes — Corrected auth flow using GitHub OAuth tokens instead of short-lived Copilot session tokens
• ✅ Improved Parsing — Handles edge cases like entitlement: 0 with fallback to percent_remaining / quota_remaining
• ✅ Provider Detection — Automatically identifies the active model provider
• ✅ Debug Mode — /usage debug <provider> for troubleshooting API responses
• ✅ Local Session Usage — Track token consumption across Pi sessions

Installation

npm install @pi/agent-extensions-pi-usages

Or copy pi-usages.ts directly to your Pi extensions directory:

cp pi-usages.ts ~/.pi/agent/extensions/

Usage

Commands

| Command | Description | |---------|-------------| | /usage | Show current provider's quota limits | | /usage <provider> | Show quota for a specific provider (anthropic, github-copilot, openai-codex, openrouter, ollama-cloud) | | /usage local | Display token usage from Pi sessions (24h, 7d, 30d) | | /usage refresh | Force-refetch quota from API and redraw overlay | | /usage debug <provider> | Dump raw API response for troubleshooting |

Examples

# Show Claude Anthropic quota
/usage anthropic

# Show GitHub Copilot quota
/usage github-copilot

# Manually refresh and see current limits
/usage refresh

# Debug Copilot API response
/usage debug github-copilot

Features

Overlay Widget

The extension displays a persistent single-row overlay below the editor showing:

• Provider name with dynamic refresh indicator
• Quota percentage bar and percentage remaining
• Token counts (when available)
• Reset time for the active window

Example:

  5s Copilot  Premium [████████░░░░░░░░] 53%  ·  Chat ∞  ·  resets 00:00 01 Jul

Automatic Polling

• Active mode (during agent processing): 30s polling intervals
• Idle mode (between requests): 60s polling intervals
• Anthropic: Longer intervals (2min) to avoid rate limits
• Indicator shows countdown timer during active mode

Token Usage Tracking

The /usage local command analyzes Pi session logs to show:

• 24h, 7d, 30d token consumption
• Input/output token breakdown
• Cache read/write tokens
• Estimated cost

Provider Setup

Anthropic

Set API key via /login or environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

GitHub Copilot

The extension automatically uses Pi's stored Copilot refresh token or your gh CLI authentication:

gh auth login
# or use /login in Pi

OpenAI Codex

Set up OAuth via /login in Pi.

OpenRouter

Set API key via /login or environment variable:

export OPENROUTER_API_KEY=...
export OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

Ollama Cloud

Set API key via /login or environment variable:

export OLLAMA_API_KEY=...

Configuration

Environment Variables

• PI_USAGE_TZ — Override display timezone (e.g., America/New_York)
• TZ — System timezone fallback
• ANTHROPIC_API_KEY — Anthropic API key
• GITHUB_TOKEN / GH_TOKEN — GitHub token for Copilot
• OPENROUTER_API_KEY — OpenRouter API key
• OPENROUTER_BASE_URL — OpenRouter base URL (default: https://openrouter.ai/api/v1)
• OLLAMA_API_KEY — Ollama Cloud API key

How It Works

GitHub Copilot Auth Flow (Fixed)

The original @porche/pi-usage had issues with GitHub Copilot authentication:

1. Problem: copilot_internal/user requires a GitHub OAuth token (ghu_/gho_), but Pi stores the Copilot session token as access (short-lived tid=…)
2. Solution: Try tokens in this order:
   • Pi refresh token (GitHub OAuth) ✅
   • gh CLI token ✅
   • Environment variables (GITHUB_TOKEN/GH_TOKEN) ✅
   • Pi access token (Copilot session) — fallback only

Quota Parsing (Fixed)

The original code had issues when entitlement: 0:

1. Problem: Limited entries were skipped when entitlement=0, even with valid percent_remaining / quota_remaining
2. Solution: Prefer percent_remaining field and derive total from remaining / percent_left when needed

Fixes vs Original

| Issue | Original | v2 | |-------|----------|-----| | Copilot auth | Only uses session token (expires quickly) | Tries OAuth token first, falls back gracefully | | Copilot parsing | Skips entries when entitlement=0 | Uses percent_remaining / quota_remaining | | Provider detection | Doesn't normalize github-copilot/model | Strips /model suffix, detects correctly | | Overlay | No persistent display | Single-row widget with auto-refresh | | Refresh | Manual only | Auto-updates, /usage refresh + debug mode |

Development

Build from Source

npm install
npx tsc --noEmit

Testing

Copy to extensions directory and reload Pi:

cp pi-usage-v2.ts ~/.pi/agent/extensions/
# Reload Pi (Cmd+Shift+P > Reload Window or /reload in Pi)

Troubleshooting

"No quota API" error

The provider isn't recognized. Check:

• Active model provider with /usage (no args)
• Explicit provider setting in ~/.pi/agent/settings.json

"Quota response received but no quota limits"

You're on an unlimited plan (e.g., Copilot Pro). The overlay still shows ∞ for unlimited slots.

"Copilot unavailable: rate limited"

Too many /usage calls in quick succession. The overlay automatically backs off retry intervals.

"No Anthropic auth"

Set ANTHROPIC_API_KEY or use /login to store OAuth token in ~/.pi/agent/auth.json.

License

MIT

Support

For issues, feature requests, or questions:

• Check ~/.pi/agent/usage-cache.json for cached quota
• Run /usage debug <provider> to see raw API responses
• Review Pi logs with /reload to ensure extension loads

Placement: ~/.pi/agent/extensions/pi-usages/ (directory with package.json)

Compatible with: Pi >= 1.0.0