FAQ

FAQ

Does it need an API key?

No. It reuses the OAuth token Claude Code already created (in ~/.claude/.credentials.json or the macOS Keychain). If the claude CLI works, the widget works. It never has credentials of its own.

Does it cost me anything / use my token budget?

The usage fetch hits a lightweight status endpoint, not a model. The only feature that calls a model is the AI weekly report (a single short Claude Haiku call, cached for an hour) — and it silently no-ops if you'd rather it didn't run.

Does it send my prompts or data anywhere?

No. It talks to Anthropic (the same endpoints Claude Code uses) and reads local files. Raw prompt text is redacted from the CLI and the localhost API. The only non-Anthropic network call is the optional news ticker, which is off by default.

Which platforms are supported?

Linux, macOS, and Windows — one pip install, Qt bundled. No apt, brew, PyGObject, or rumps required.

How is this different from the claude.ai usage page?

Same numbers, always-on-top, no browser. Plus live tokens/min, a per-turn cost ticker, forecasts, heatmaps, per-model cost breakdown, an AI weekly summary, CLI/API surfaces, and webhooks.

Can I run it headless / in the background?

Yes: claude-usage --detach double-forks and logs to ~/.cache/claude-usage/widget.log. For autostart, see Installation.

How do I move / resize it?

Drag with left-click to move (the spot is remembered); scroll to resize (0.6×–2.0×, remembered). Or right-click → OSD Position ▸ for corner presets. See Usage.

Why did my reset countdown blank for a second?

Almost always a transient API rate-limit. Fixed to degrade gracefully in v0.8.3+; raise refresh_seconds if you still see it. See Troubleshooting.

Can I use it in my status bar (tmux/waybar/polybar)?

Yes — that's what --field and the localhost JSON API are for. See Shell Integrations.

How do I change the theme?

Right-click → Theme ▸, or set "theme" in config.json. 11 options — see Themes.

Where's the config file?

~/.config/claude-usage/config.json. It's created and updated automatically as you use the menu; you can also hand-edit it. Full key list in Configuration.

How do I update?

pip install --user --upgrade claude-usage-widget (or brew upgrade claude-usage-widget), then restart the widget. An Update available banner also appears in the right-click menu when a new release lands.

It's not showing — what now?

See Troubleshooting → "OSD not visible".