Coding Agent Rate Limit Indicator

A GNOME Shell extension that monitors rate limit usage for multiple coding agent services in the top bar.

Features

• Multi-provider support: Monitor Claude Code (Anthropic), Codex (OpenAI), Antigravity CLI (Google), GLM (z.ai), and more
• Multi-account: Configure multiple accounts per provider
• Top bar indicator: Concise usage display with text, progress bar, or both; SVG provider icons fetched from CDN and cached locally
• Detailed popup menu: Per-account breakdown with progress bars, reset timers, and usage percentages; theme-adaptive colors for light/dark GNOME Shell themes
• Color-coded usage: Green → Yellow → Orange → Red as usage increases
• Extensible architecture: Clean provider pattern makes it easy to add new services
• Secure credential storage: Tokens stored in GNOME Keyring (Secret Service)
• Auto-detect credentials: Claude Code, Codex, and Antigravity read OAuth tokens from local config automatically
• Safe credential handling: For CLI-managed providers (Claude, Codex) the extension is a read-only consumer — it never refreshes or rewrites the CLI's auth file. Antigravity tokens, which the extension owns, are refreshed automatically.
• Rate limit resilience: 429 responses trigger per-account backoff using Retry-After header
• Proxy support: Optional HTTP proxy for all API requests

Supported Providers

Provider	Auth Method	API
Claude Code (Anthropic)	Auto-detect from ~/.claude/.credentials.json	Anthropic OAuth Usage API
Codex (OpenAI/ChatGPT)	Auto-detect from ~/.codex/auth.json	ChatGPT Internal API
Antigravity	Native Browser OAuth	Google Cloud Code API
GLM (z.ai)	Manual API key	z.ai Monitor API

Notes:

• The Antigravity provider uses the Google Code Assist backend.

Adding a new provider

The extension uses a clean provider pattern. To add support for a new coding agent:

1. Create a new file in providers/ extending BaseProvider
2. Implement fetchUsage() returning normalized UsageResult data
3. Register the provider in providerRegistry.js

See providers/base.js for the interface definition and providers/claude.js for a reference implementation.

Requirements

• GNOME Shell 45 or later (Ubuntu 24.04+, Fedora 40+, etc.)
• libsoup3 (usually pre-installed)
• libsecret / GNOME Keyring (usually pre-installed)

Installation

From source

git clone https://github.com/hans/coding-agent-rate-limit-indicator.git
cd coding-agent-rate-limit-indicator
chmod +x install.sh
./install.sh

Then restart GNOME Shell and enable the extension:

# On X11: Alt+F2 → r → Enter
# On Wayland: log out and back in

gnome-extensions enable coding-agent-rate-limit-indicator@github.com

Configuration

Open the extension preferences via GNOME Extensions app or:

gnome-extensions prefs coding-agent-rate-limit-indicator@github.com

General Settings

• Refresh interval: 900–86400 seconds (default: 1800)
• Display mode: Text, Progress Bar, or Both
• Time display: Remaining reset countdown or local recovery time in the panel
• HTTP Proxy: Optional proxy URL for API requests

Account Setup

Claude Code

1. Open extension preferences → Accounts tab
2. Click "Add Claude Code account"
3. Enter a display name (e.g., "Work", "Personal")
4. The extension auto-detects your OAuth token from ~/.claude/.credentials.json
5. For multiple Claude accounts, specify different credential file paths

Codex (OpenAI)

1. Open extension preferences → Accounts tab
2. Click "Add Codex account"
3. Enter a display name
4. The extension auto-detects your OAuth token from ~/.codex/auth.json (written by the Codex CLI after login)
5. For a custom credential file location, set the CODEX_HOME environment variable or specify a path in account settings

GLM (z.ai)

1. Open extension preferences → Accounts tab
2. Click "Add GLM account"
3. Enter a display name
4. Enter your z.ai API key in the token field
   • Log in to z.ai and generate an API key from your account settings

Antigravity

1. Open extension preferences → Accounts tab
2. Click "Add Antigravity account"
3. Click the "Login with Antigravity" button in the dialog.
4. Your default browser will open. Authenticate with your Google account.
5. Once authenticated, the OAuth Refresh Token will be automatically filled in.
6. Choose the per-account panel quota strategy:
   • Most constrained: show the tightest quota bucket in the panel
   • Pooled first: prefer the pooled bucket when available
   • Pooled only: show only the pooled bucket in the panel
7. To re-authenticate later, expand the account in Preferences → Accounts and click "Re-login with Antigravity".

Architecture

├── extension.js          # Main entry point, panel UI, popup menu, refresh logic
├── prefs.js              # Preferences window (libadwaita)
├── constants.js          # Shared constants
├── accounts.js           # Multi-account CRUD operations
├── secret.js             # GNOME Keyring integration
├── iconCache.js          # Fetches and caches provider SVG icons from CDN
├── providerRegistry.js   # Provider registration and lookup
├── providers/
│   ├── base.js           # Base provider interface
│   ├── claude.js         # Claude Code (Anthropic) provider
│   ├── codex.js          # Codex (OpenAI) provider
│   ├── antigravity.js    # Antigravity CLI (Google) provider
│   └── glm.js            # GLM (z.ai) provider
├── schemas/              # GSettings schema
├── stylesheet.css        # Extension styles
├── install.sh            # Installation script
└── uninstall.sh          # Uninstallation script

Design Principles

• Separation of concerns: Display layer (extension.js) is fully decoupled from data fetching (providers/)
• Normalized data model: All providers return the same UsageResult format regardless of API differences
• Multi-account first: Every provider supports multiple accounts from day one
• Graceful degradation: Shows stale data with a marker when refresh fails, never crashes

Acknowledgments

Inspired by these excellent GNOME Shell extensions:

• claude-usage-extension by Haletran
• ccusage-indicator by lordvcs
• codex-usage-indicator by stonega

License

MIT License. See LICENSE for details.

This extension is not affiliated with, funded by, or associated with Anthropic, OpenAI, Google, or Antigravity.