AI Usage Monitor

Overview

Pi Island includes a built-in AI usage monitor that tracks your subscription quotas across multiple AI service providers. Access it by clicking the chart icon (📊) in the sessions header.

Supported Providers

Anthropic (Claude)

Tracks Claude Pro/Max subscription usage:

• 5h window: Short-term rate limit (resets every 5 hours)
• Week: Weekly usage quota
• Extra Usage: Pay-as-you-go usage when enabled

Credentials: Read from ~/.pi/agent/auth.json (via pi login anthropic) or macOS Keychain (Claude Code).

GitHub Copilot

Tracks Copilot Pro/Business subscription:

• Month: Monthly premium interactions quota (e.g., 1239/1500)

Credentials: Read from ~/.pi/agent/auth.json (via pi login github-copilot).

Google Gemini CLI

Tracks Google Cloud Code Assist quotas:

• Pro: Gemini Pro model quota
• Flash: Gemini Flash model quota

Credentials: Read from ~/.pi/agent/auth.json (via pi login google-gemini-cli) or ~/.gemini/oauth_creds.json.

Google Antigravity

Tracks per-model quotas for all available models:

• Gemini 2.5 Pro, Gemini 3 Pro, GPT-OSS, and other available models
• Each model shows its individual quota and reset time

Credentials: Read from ~/.pi/agent/auth.json (via pi login google-antigravity).

Synthetic

Tracks Synthetic API quotas:

• Subscription: Main monthly quota
• Search/hr: Hourly search request quota
• Tool Calls: Daily tool call discount quota

Credentials: Read from the SYNTHETIC_API_KEY environment variable.

Features

Progress Bars with Linear Pace

Each quota displays a progress bar showing:

• Green fill: Current usage percentage
• White marker: Expected linear usage based on time elapsed in the period

This helps you understand if you're using your quota faster or slower than a linear pace.

Pace Indicators

• ↑ Arrow (orange): You're ahead of linear pace (using faster than expected)
• ↓ Arrow (green): You're behind linear pace (using slower than expected)

A 5% buffer prevents arrows from showing for minor fluctuations.

Period Bounds

Each quota shows detailed period information:

• Start date/time: When the current period began
• End date/time: When the quota resets
• Elapsed: Time since period started
• Remaining: Time until reset

Automatic Refresh

The usage monitor automatically refreshes:

• Default interval: 60 seconds
• Configurable via settings
• Manual refresh via the refresh button (↻)

Notifications

When running as a bundled app, Pi Island can notify you:

• Warning: When usage exceeds 80% (configurable)
• Critical: When usage exceeds 95% (configurable)
• Reset: When a quota resets

Setting Up Providers

Using Pi CLI

The easiest way to set up credentials is via the Pi CLI:

# Anthropic
pi login anthropic

# GitHub Copilot
pi login github-copilot

# Google Gemini CLI
pi login google-gemini-cli

# Google Antigravity
pi login google-antigravity

Environment Variables

Some providers support environment variables:

# Synthetic
export SYNTHETIC_API_KEY="syn_your_api_key_here"

Credential Locations

Pi Island reads credentials from these locations (in priority order):

Troubleshooting

Provider Shows "EXPIRED"

OAuth tokens have expired. Re-authenticate:

pi login <provider-name>

Provider Shows "NO_CREDS"

No credentials found. Set up the provider:

pi login <provider-name>

Or set the appropriate environment variable.

Provider Not Appearing

Providers without valid credentials are automatically hidden. Check:

1. Credentials are properly configured
2. Environment variables are set in your shell profile
3. Restart Pi Island after adding new credentials

Notifications Not Working

Notifications require:

• Pi Island to be running as a bundled .app
• Notification permissions granted in System Preferences
• notificationsEnabled setting to be true