opencode-v2-gemini-usage-billing

OpenCode V2 plugin for real-time tracking of Google Gemini API Key Usage, Sliding-Window Rate Limits (RPM, TPM, RPD), Spend (USD / IDR), and Google Cloud Billing.

Designed specifically for developers using Google Gemini models (gemini-3.8-flash, gemini-2.5-pro, gemini-2.5-flash, etc.) in OpenCode V2.

✨ Features

• 🔑 Automatic Gemini Auth Discovery: Reads your configured Google credentials directly from OpenCode's local database (~/.local/share/opencode/opencode.db) or fallbacks to environment variables (GEMINI_API_KEY / GOOGLE_API_KEY).
• ⚡ Live Reactive Sliding-Window Rate Limits:
  • Real-time 60-second sliding window for Requests Per Minute (RPM) and Tokens Per Minute (TPM) with an instant 1-second clock decay.
  • Accounts for full input context throughput including Prompt Context Caching (cache.read) matching Google AI Studio calculations.
  • Daily request quota tracking (RPD) reset at midnight Pacific Time.
• 🎨 Dynamic Color Saturation Meters:
  • Visual mini saturation meters ([████░░]) matching OpenCode's semantic theme tokens.
  • 🟢 Green (< 65%): Normal safe operating capacity.
  • 🟠 Amber (65%–85%): High throughput approaching limit.
  • 🔴 Red (> 85%): Near quota limit / throttled.
• 🏷️ Tier-Level Awareness:
  • Automatically identifies Gemini tier: Free, Tier 1, Tier 2, or Tier 3 based on model access and spend history.
  • Model-specific rate limits for gemini-3.8-flash (2M TPM, 1k RPM in Tier 1 per Google AI Studio specifications).
  • Custom quota overrides via GEMINI_TPM_LIMIT, GEMINI_RPM_LIMIT, and GEMINI_RPD_LIMIT.
• 💰 Accurate Spend & Google Cloud Billing Synchronization:
  • Real-time session spend bound directly to OpenCode's in-memory session store (context.data.session.cost).
  • Tiered spend overview: Current Session, Today, This Month, and All-Time.
  • Google Cloud ADC Integration: Discovers active Google Cloud billing accounts via authenticated gcloud credentials, automatically localizing spend into IDR (Indonesian Rupiah) matching Google AI Studio's billing dashboard.
• 🖥️ OpenCode TUI Integration:
  • Collapsible Sidebar Widget (sidebar.content): Clean, narrow-sidebar safe layout (~25–29 characters) with persistent collapse state via context.storage.store.
  • Footer Status Bar (home.footer.status): Lightweight real-time ticker showing current spend and RPM.
• 🤖 Agent Tool (gemini_usage_report):
  • Exposes an OpenCode server tool allowing agents to programmatically query live usage, active rate limits, and billing metrics.

🚀 Installation & Setup

1. Install Plugin

Add opencode-v2-gemini-usage-billing to your opencode.json(c):

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    "opencode-v2-gemini-usage-billing"
  ]
}

Or for global terminal TUI access in ~/.config/opencode/cli.json:

{
  "plugins": [
    "opencode-v2-gemini-usage-billing"
  ]
}

2. Gemini Authentication

This plugin automatically retrieves your Google API Key from OpenCode's database:

• ~/.local/share/opencode/opencode.db (credential table where integration_id = 'google')

Alternatively, you can export environment variables:

export GEMINI_API_KEY="AIzaSy..."
# or
export GOOGLE_API_KEY="AIzaSy..."

🕹️ Sidebar Preview

Collapsed Header

▶ Gemini Usage (Rp 96K · 6 RPM)

Expanded Sidebar Panel

▼ Gemini Usage
  Auth         AIzaSy...Ln64 (Tier 1)
  Status                   🟢 Normal
  Spend (Session)             Rp 96K ($6.00)
    Today                    Rp 208K ($13.01)
    This Month               Rp 921K (IDR)
    All-Time                 Rp 921K
  RPM (1m)         6 / 1k  [█░░░░░]
  TPM (1m)     1.52M / 2M  [█████░]
  Daily (24h)    683 / 10k [█░░░░░]
  Active Models:
   • gemini-3.8-flash  118.9M
  AI Studio Usage  aistudio.google.com

⚙️ Environment Variables & Overrides

| Variable | Description | Default | |---|---|---| | GEMINI_TIER | Force tier level (tier1, tier2, tier3, free) | Auto-detected | | GEMINI_TPM_LIMIT | Override Tokens Per Minute limit (e.g. 2000000) | Tier standard | | GEMINI_RPM_LIMIT | Override Requests Per Minute limit (e.g. 1000) | Tier standard | | GEMINI_RPD_LIMIT | Override Daily Requests limit (e.g. 10000) | Tier standard | | GEMINI_CURRENCY | Currency code (IDR or USD) | Auto from billing account | | GEMINI_EXCHANGE_RATE| Exchange rate for USD to IDR conversion | 16000 | | GCLOUD_PATH | Path to gcloud binary for ADC billing lookup | Auto-detected |

📐 Rate Limits Reference

Gemini 3.8 Flash

| Tier | RPM | TPM (Input) | RPD (Daily) | |---|---|---|---| | Free Tier | 5 | 250,000 | 20 | | Tier 1 | 1,000 | 2,000,000 (2M) | 10,000 | | Tier 2 | 2,000 | 3,000,000 (3M) | 100,000 | | Tier 3 | 4,000 | 6,000,000 (6M) | 200,000 |

Gemini 2.5 Pro

| Tier | RPM | TPM (Input) | RPD (Daily) | |---|---|---|---| | Free Tier | 2 | 32,000 | 50 | | Tier 1 | 360 | 2,000,000 (2M) | 5,000 | | Tier 2 | 1,000 | 4,000,000 (4M) | 10,000 | | Tier 3 | 2,000 | 8,000,000 (8M) | 20,000 |

Useful links:

• Google AI Studio Rate Limits: https://aistudio.google.com/rate-limit
• Google Cloud Console Billing: https://console.cloud.google.com/billing

🛠️ Development

# Install dependencies
bun install

# Run test suite
bun test

# Build distribution files
bun run build

# Typecheck
bun run check

📄 License

MIT © Ahmad Nawawi