Claude Usage Monitor for Cinnamon

Keep your Claude plan usage beautifully in view — right in your Cinnamon panel.

Full usage overview with the plan pill and the Fable week	A horizontal panel with the Fable week and the extra usage left as panel items

Only the session and the week? The popup trims to the essentials

_{Same values as above — with model limits switched off the popup stays sleek.}

Every active limit at a glance

_{Hovering the panel icon summarizes every window with its remaining quota.}

General settings	Colors and thresholds

Why you will love it

• Everything at a glance — the 5-hour session and the all-models week as rings in the panel and the popup, with live reset countdowns. Either panel window can be hidden when you prefer it calm, model weeks such as Fable can join the panel as items of their own, and so can the extra usage left.
• Model weeks, stacked — Fable, Sonnet, Opus and every other model-scoped weekly limit Claude reports get their own section, always open; extra usage shows the purchased credits still left, as claude.ai lists them, in Claude's terracotta in the popup and the activity graph.
• Sign-in reuse, no setup — the applet reads the Claude Code login you already have; an opt-in switch lets Claude Code sign in again when it expires. Without a login it still shows the session and weekly percentages that Claude Desktop records for itself.
• Read-only and careful — one GET to Anthropic's usage endpoint per refresh and tried token (plus a profile lookup at most every 12 hours and, while extra usage is on, one GET for the purchased credits left). The applet never refreshes, writes or logs a token itself.
• Built for real panels — horizontal and vertical panels, threshold colors, pinned header and action footer, and a scrollable popup that never lets content escape.

Installation

./install.sh

Then enable Claude Usage Monitor via System Settings → Applets and add it to a panel. Requires Python 3.10+ and Cinnamon 5.8 or newer.

Where the numbers come from

1. Claude's usage endpoint (full data: reset times, model weeks, extra usage) with the first accepted token from

   • the optional Claude OAuth token applet setting (masked),
   • the CLAUDE_CODE_OAUTH_TOKEN environment variable,
   • the file ~/.config/cinnamon-claude-usage/oauth-token,
   • the Claude Code login in ~/.claude/.credentials.json ($CLAUDE_CONFIG_DIR is honored) — run claude auth login once.

   A rejected token falls through to the next source.

2. Claude Desktop's own samples (~/.config/Claude/plan-usage-history.json) when no usable token exists: session and weekly percentages without reset times or scoped weeks such as Fable — the rows then simply skip the reset line.

If the endpoint is busy or unreachable right after a reload, the popup shows the last good state of the same login (taken within the last two hours, with its original "Updated" time) until the endpoint answers again. The refresh interval starts at 2 minutes, and the endpoint is asked at most every 110 seconds per login: Refresh now, a reload or a setting change in between shows the last answer again (at a one-minute pace the endpoint rejects about every second request with HTTP 429).

Without a login the footer offers Sign in to Claude Code: it runs claude auth login in a terminal (a fresh sign-in, which replaces the logins the CLI stores) and the applet refreshes as soon as the login is stored.

Claude Code logins expire after 8 hours; Claude Code renews them whenever you use the CLI. If you mostly work in Claude Desktop, switch on Renew the Claude Code login automatically (off by default): the applet then runs claude auth login with the expired login's refresh token. That is a complete re-login by Claude Code — it replaces every login the CLI stores (for example Claude Design or cloud sessions), resets its trusted-device state and is recorded like any sign-in, which is why it is opt-in. After about a month the refresh token ends too; sign in again with claude auth login. Long-lived claude setup-token tokens lack the user:profile scope the usage endpoint requires.

The popup

Zone	What you get
Header (pinned)	Title, the gradient plan pill, the last-update stamp and the 5h / 7d rings
Usage limits	The 5-hour session and the week plus Fable / Sonnet / Opus sections with countdowns
Extra usage	The purchased credits left plus the 24h/12h/4h/1h spend; the monthly limit only while it ends spending first
Recent consumption	Per-window 1h/4h/12h/Today summaries and the 24-hour activity charts
Footer (pinned)	Claude, Claude Code, Refresh now, Usage settings — plus Sign in to Claude Code while no login feeds the applet

The Claude and Claude Code buttons open Claude Desktop's new-chat and new-session deep links when Claude Desktop is installed, otherwise the web app and the CLI in a terminal.

Links

• Development, architecture and the fork/backport guide: docs/README.md
• Sibling applets: cinnamon-z-usage (Z.ai GLM Coding Plan) and cinnamon-chatgpt-usage (ChatGPT Work & Codex)

Credits

Built with love by Claudiu & Claude as part of OSS Singularity. Forked from cinnamon-z-usage, itself a fork of cinnamon-chatgpt-usage. All bundled icons are original OSS Singularity artwork (GPL-3.0-or-later) except the bundled symbolic action icons from Ubuntu Yaru; see icons/ATTRIBUTION.md.

Claude Usage Monitor is an independent community project. It is not affiliated with, endorsed by or sponsored by Anthropic. Claude and Claude Code are trademarks of Anthropic, PBC, used here only to name the services the applet reads.

Licensed under GPL-3.0-or-later.