Claude Usage Widget

A KDE Plasma 6 widget that displays your Claude Code usage statistics in the taskbar.

Features

• 3 Panel Styles: Ring (anti-aliased progress rings), Text (percentage + dot), Bar (vertical bars with time marker)
• Time-Proportional Coloring: Colors based on elapsed time vs usage ratio (configurable, can switch to fixed 50/80/100% thresholds)
• Card Popup: Modern card-based popup with configurable card order and visibility (via settings)
  • Account info, session & weekly usage rings, per-model breakdown, extra usage, token stats, trend chart, installations, quick links
• Classic Popup: Traditional layout with progress bars (switchable in settings)
• Desktop Notifications: Alerts when usage crosses thresholds (50/80/95% session, 95% weekly, quota reset)
• Update Checker: Orange dot on panel icon when a new Claude Code version is available
• Process Visibility: Hide widget or usage when Claude is not running
• Configurable Refresh: Default 5 min polling (adjustable in settings)
• Smart Rate Limit Handling: Uses retry-after header, exponential backoff, and token watcher for automatic recovery
• Local Cache: Remembers last data on restart (up to 24h)
• Stale Detection: Widget dims when data is outdated
• Error Handling: Clear messages when not logged in, token expired, or rate limited
• Custom API Support: Optional proxy/gateway with custom base URL and API key
• Configurable Background Opacity: Adjustable transparency for desktop placement
• 15 Languages: EN, HU, DE, FR, ES, IT, PT, RU, PL, NL, TR, JA, KO, ZH-CN, ZH-TW
• No Dependencies: Pure QML, no Python or external tools required

Requirements

• KDE Plasma 6.0 or later
• Claude Code CLI installed and logged in

Installation

From KDE Store

1. Right-click on your panel
2. Select "Add Widgets..."
3. Click "Get New Widgets..." > "Download New Plasma Widgets..."
4. Search for "Claude Usage"
5. Click Install

Manual Installation

kpackagetool6 -t Plasma/Applet -i claude-usage-widget.plasmoid

From Source

git clone https://github.com/izll/plasma-claude-usage.git
cd claude-usage-widget
kpackagetool6 -t Plasma/Applet -i .

Usage

1. Make sure you're logged in to Claude Code (run claude in terminal)
2. Add the widget to your panel
3. Click the widget to see detailed usage statistics

Configuration

Right-click the widget and select Configure... to open the settings.

Custom API Base URL (optional)

By default the widget reads your OAuth credentials from ~/.claude/.credentials.json and calls https://api.anthropic.com directly — no configuration needed.

If you use a custom API proxy or gateway, you can override this:

Setting	Description
Base URL	Your proxy URL, e.g. https://your-proxy.example.com
API key	Your ANTHROPIC_API_KEY

Note: The widget calls /api/oauth/usage, not the standard /v1/messages endpoint. Use the root URL without any path suffix — e.g. https://api.anthropic.com, not https://api.anthropic.com/v1.

When a base URL is configured, the widget authenticates with x-api-key instead of the OAuth token. Leave the Base URL field empty to go back to the default credentials file method.

How It Works

The widget calls the Anthropic usage API directly from QML. No data is stored or sent anywhere else.

API Endpoint

GET https://api.anthropic.com/api/oauth/usage
Headers:
  Authorization: Bearer <oauth-token>   (default mode)
  x-api-key: <api-key>                  (custom base URL mode)
  anthropic-beta: oauth-2025-04-20

Troubleshooting

"Not logged in" error

Make sure you're logged in to Claude Code:

claude

"Token expired" error

Your OAuth token has expired. Run Claude Code again to refresh it:

claude

The widget also has an "Open Claude" button for this.

"Rate limited" error

The API allows ~4 requests per 5-minute window. The widget handles this automatically:

• Reads the retry-after header and waits the specified time
• Falls back to exponential backoff (5/10/15 min)
• Monitors for token refresh and recovers instantly

To avoid rate limiting, keep the refresh interval at 5 minutes or higher.

"Invalid API key" error

The API key in the widget settings is wrong or revoked. Open Configure... and update it.

"Endpoint not found — check base URL" error

The base URL in the widget settings doesn't point to a valid API. Make sure you're using the root URL without /v1, e.g. https://api.anthropic.com.

Widget shows 0%

• Click the refresh button in the popup
• Check logs: journalctl --user -f | grep -i claude

File Structure

claude-usage-widget/
├── metadata.json              # Widget metadata
├── install.sh                 # Installation script
├── contents/
│   ├── config/
│   │   └── main.xml           # Configuration schema
│   ├── ui/
│   │   ├── main.qml           # Core logic, data, API
│   │   ├── CompactView.qml    # Panel representation (text/bar/ring)
│   │   ├── FullView.qml       # Card popup with drag & drop
│   │   ├── UsageRing.qml      # Anti-aliased progress ring component
│   │   ├── ModelRow.qml       # Model breakdown row component
│   │   ├── TrendChart.qml     # 7-day trend chart component
│   │   ├── configGeneral.qml  # Settings UI
│   │   └── Translations.qml   # i18n (15 languages)
│   └── icons/
│       ├── claude.svg         # Claude logo (orange)
│       └── claude-tile.svg    # Claude tile icon
└── screenshots/               # Preview images

License

GPL-3.0-or-later

Author

izll

Changelog

See CHANGELOG.md for a detailed version history.