@porche/pi-usage

Overview

pi-usage brings a native, Hermes-style /usage command to the Pi Coding Agent. It provides complete visibility into your token consumption without spending LLM tokens to query it.

Every time you run /usage, it displays:

1. Live Session Token Usage: The exact tokens (input, output, and context window percentage) spent in your current active session.
2. Provider Account Limits: The real-time remaining quota from your active provider's API (e.g., ChatGPT Plus 5-hour limits, GitHub Copilot monthly quotas, OpenRouter credits).
3. Graceful Fallback: If your active provider (like Google Gemini) does not expose a public quota API, it automatically falls back to local historical usage computed directly from your Pi session files.

Installation

Install directly from GitHub into your Pi environment:

pi install git:github.com/aporcelli/pi-usage

After installation, reload your Pi session:

/reload

Commands

• /usage Detects your active provider and displays session token usage and API limits for that provider.

• /usage limits Checks account limits for the active provider only.

• /usage Checks account limits for a specific provider. Supported providers: openai-codex, anthropic, github-copilot, openrouter.

• /usage local Bypasses provider APIs completely and calculates historical token usage (24h, 7d, 30d) directly from your Pi session files.

How It Works Under the Hood

1. Smart Active Provider Inference

Pi extensions run synchronously in the UI. To accurately determine what model you are using (even if you just ran /model or resumed a session with --resume), the extension uses a robust fallback chain:

1. Direct API: ctx.getModel()?.provider
2. Context model: ctx.model?.provider
3. Session History: Scans the session branch backwards for the last model_change event.
4. Global Settings: defaultProvider from ~/.pi/agent/settings.json.

2. Pi-Native Authentication

The extension does not use hardcoded paths. It reads credentials natively from Pi:

• Checks ~/.pi/agent/auth.json first (for OAuth tokens generated via Pi's /login or saved API keys).
• Falls back to standard environment variables (e.g., ANTHROPIC_API_KEY, OPENROUTER_API_KEY, GITHUB_TOKEN/GH_TOKEN).
• For GitHub Copilot, it also falls back to gh auth token automatically when available.

3. Portable Timezone Formatting

Reset times (e.g., "Resets: 15:00 on 12 May") are automatically localized. You can force a specific timezone by setting an environment variable. Resolution order:

1. PI_USAGE_TZ environment variable (e.g., export PI_USAGE_TZ=America/Argentina/Buenos_Aires)
2. TZ environment variable
3. System runtime timezone (Intl.DateTimeFormat)
4. UTC (fallback)

UI & UX

The terminal output uses specialized formatting:

• Visual Progress Bars: [██████████░░░░] 60%
• Traffic Light Indicators: 🟢 (>70% remaining), 🟡 (30-70% remaining), 🔴 (<30% remaining).
• Absolute Countdowns: Clearly shows exactly when limits reset (in 2h 15m).

Troubleshooting

• "No limits data" or "Unavailable": Ensure you have logged in via /login in Pi (for OAuth providers) or that your API keys are exported in your shell.
• GitHub Copilot unavailable: run gh auth login (or export GITHUB_TOKEN) so /usage github-copilot can resolve a valid token fallback.
• Wrong Reset Timezone: Export PI_USAGE_TZ in your shell profile.
• "local usage unavailable": Verify that ~/.pi/agent/sessions exists and contains Pi session .jsonl files.

License

MIT