A KDE Plasma 6 widget that displays your Claude Code usage statistics in the taskbar.
- 3 Panel Styles: Ring (anti-aliased progress rings), Text (percentage + dot), Bar (vertical bars with time marker)
- Panel Customization: Metrics size (100–300%), ring center (percent, Claude logo, or logo + percent) with adjustable logo size, 5h/7d window labels, panel margin and icon size
- 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
- Widget Update Notice: Green badge in the popup when a newer version of the widget is on the KDE Store, opening "Get New Widgets"
- 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-afterheader, 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
- Custom Credentials Location: Point the widget at another
.credentials.jsonor Claude config folder - 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
- KDE Plasma 6.0 or later
- Claude Code CLI installed and logged in
- Right-click on your panel
- Select "Add Widgets..."
- Click "Get New Widgets..." > "Download New Plasma Widgets..."
- Search for "Claude Usage"
- Click Install
kpackagetool6 -t Plasma/Applet -i claude-usage-widget.plasmoidgit clone https://github.com/izll/plasma-claude-usage.git
cd claude-usage-widget
kpackagetool6 -t Plasma/Applet -i .- Make sure you're logged in to Claude Code (run
claudein terminal) - Add the widget to your panel
- Click the widget to see detailed usage statistics
Right-click the widget and select Configure... to open the settings. They are grouped into tabs:
- General: language, refresh interval, notifications, update check, colors, visibility when Claude is not running
- Panel: style, what to show, layout, metrics size, margin, ring center and logo size, window labels, icon
- Popup: card or classic style, scrolling, desktop background opacity, card order, quick links
- Account: credentials location, automatic session refresh, custom API
By default the widget reads your OAuth credentials from $CLAUDE_CONFIG_DIR/.credentials.json, falling back to ~/.claude/.credentials.json when that variable is not set — no configuration needed.
Because plasmashell does not inherit your shell environment, $CLAUDE_CONFIG_DIR is only visible to the widget if it was exported before your session started. If it wasn't, or if you keep your credentials somewhere else entirely, set the path explicitly:
| Setting | Description |
|---|---|
| Credentials path | Either the file itself, e.g. ~/work/.credentials.json, or the folder that contains it, e.g. ~/work |
A value ending in .json is treated as the file; anything else is treated as the Claude config folder and /.credentials.json is appended. A leading ~ is expanded; $VARIABLES inside the value are not.
That same folder is also used for the account file (.claude.json, for your e-mail address and plan) and for the projects/ scan behind today's token stats, and it is passed as CLAUDE_CONFIG_DIR to the claude process started by the Open Claude button and by the silent session refresh — so pointing the widget at a second account moves the whole popup to that account, not just the token.
Leave the field empty to go back to the default behaviour.
If you use a custom API proxy or gateway, the widget can skip the credentials file entirely and call your endpoint with an API key instead.
| 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/messagesendpoint. Use the root URL without any path suffix — e.g.https://api.anthropic.com, nothttps://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.
The widget calls the Anthropic usage API directly from QML. No data is stored or sent anywhere else.
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
Make sure you're logged in to Claude Code:
claudeYour OAuth token has expired. Run Claude Code again to refresh it:
claudeThe widget also has an "Open Claude" button for this.
The API allows ~4 requests per 5-minute window. The widget handles this automatically:
- Reads the
retry-afterheader 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.
The API key in the widget settings is wrong or revoked. Open Configure... and update it.
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.
- Click the refresh button in the popup
- Check logs:
journalctl --user -f | grep -i claude
claude-usage-widget/
├── metadata.json # Widget metadata
├── install.sh # Installation script
├── contents/
│ ├── config/
│ │ ├── config.qml # Settings tabs
│ │ └── 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: General tab
│ │ ├── configPanel.qml # Settings: Panel tab
│ │ ├── configPopup.qml # Settings: Popup tab
│ │ ├── configAccount.qml # Settings: Account tab
│ │ └── Translations.qml # i18n (15 languages)
│ └── icons/
│ ├── claude.svg # Claude logo (orange)
│ └── claude-tile.svg # Claude tile icon
└── screenshots/ # Preview images
GPL-3.0-or-later
izll
See CHANGELOG.md for a detailed version history.