Claude Usage Panel

Claude Usage Panel

See your Claude Code plan usage at a glance — in the GNOME top bar, the macOS menu bar, under your Claude Code prompt, or by just asking Claude.

Session, weekly, and per-model limits (Fable, Opus…) — the same numbers as /usage, always visible, auto-refreshing. Plus an optional Cursor team-spend section.

---

Install

One line — it detects your platform and installs the sensible set:

curl -fsSL https://fschmutz.github.io/claude-usage-panel/install | bash

One-click Add to Cursor / Install in Claude Code buttons live on the install page →

Name targets to be explicit (bash -s -- through the one-liner, or ./install.sh from a clone):

| Target | What you get | Details | |---|---|---| | gnome | Top-bar panel + dropdown, alerts, sparklines (GNOME Shell 45–50) | [docs/GNOME.md](docs/GNOME.md) | | macos | Native SwiftUI menu-bar app, starts at login (macOS 13+) | [macos/README.md](macos/README.md) | | statusline | One-line usage gauge under the Claude Code prompt | [claude-code/README.md](claude-code/README.md) | | mcp | get_usage tool inside Claude Code and Cursor — ask "how much of my plan have I used?" | [mcp/README.md](mcp/README.md) |

The status line renders like this, right under the prompt input:

Context ▌░░░░░ 8%  Session █▌░░░░ 26% 59m  Week █▌░░░░ 24% 4d2h  ∑ 1.2M tok

Everything is reversible and idempotent: update --pull upgrades what you have, --uninstall [target…] reverses it, --dry-run previews, --list shows what's detected and installed.

The MCP tool also installs without any clone — as a Claude Code plugin (/plugin marketplace add fschmutz/claude-usage-panel, then /plugin install claude-usage@claude-usage-panel) or one CLI line (claude mcp add claude-usage -- npx -y github:fschmutz/claude-usage-panel).

Why this one

Most Claude usage indicators read the endpoint's legacy five_hour / seven_day fields and show only the aggregate session + weekly pair. This one reads the modern limits[] array, so it shows every limit the Claude app shows — including per-model weekly limits (Fable, Opus…) that the others miss — on both Linux and macOS, with native UI on each (no Electron), plus terminal and in-conversation projections.

| | | |---|---| | 📊 All plan limits | Session, weekly, per-model — one card each, severity colors + reset timers from the API | | 🔔 Alerts + sparklines | Desktop notification at 90% / 100%, tiny trend graph per limit | | 💲 Optional extras | Local ccusage session cost · Cursor team spend via Admin API | | 🔒 Read-only & private | Uses your existing local token, never writes it, no telemetry, talks only to official APIs |

Screenshots

| Dropdown | Settings | |---|---| | | |

How it works

Every client reads the OAuth token Claude Code already stores locally (~/.claude/.credentials.json on Linux, the login Keychain on macOS) and calls the official usage endpoint:

GET https://api.anthropic.com/api/oauth/usage
    authorization: Bearer 
    anthropic-beta: oauth-2025-04-20

The response's limits[] array drives one card per limit. If the token expires, the panel tells you to run any Claude Code command (which refreshes it) — it never writes the token itself. The status line is even cheaper: it renders purely from what Claude Code pipes on stdin, no credentials or network at all. The optional extras stay just as private: cost runs ccusage locally against ~/.claude/projects/*.jsonl, and Cursor spend calls api.cursor.com with your own admin key.

Documentation

| Doc | Covers | |---|---| | [docs/GNOME.md](docs/GNOME.md) | GNOME install, Wayland relog, settings, nested-shell testing | | [macos/README.md](macos/README.md) | macOS build, release, notarization, Homebrew cask | | [claude-code/README.md](claude-code/README.md) | Status line segments, token modes, manual setup | | [mcp/README.md](mcp/README.md) | MCP server, get_usage tool, all four install paths | | [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, pre-commit hooks, parity-test contract | | [PUBLISHING.md](PUBLISHING.md) | Store listings, release flow | | [CHANGELOG.md](CHANGELOG.md) | Version history |

Roadmap

• [ ] extensions.gnome.org listing (needs a GNOME store account — [PUBLISHING.md](PUBLISHING.md))
• [ ] Notarized macOS .app + Homebrew cask (needs an Apple Developer signing cert)

License

MIT — see [LICENSE](LICENSE).

---

Keywords: Claude Code usage monitor · Claude usage GNOME Shell extension · Claude plan limits top bar · macOS menu bar Claude usage · Claude Code status line usage · Claude usage MCP server · Add to Cursor MCP · Anthropic usage API · ccusage · Fable / Opus per-model weekly limit · Cursor Admin API spend · Ubuntu GNOME extension · SwiftUI MenuBarExtra

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fschmutz
• Source: fschmutz/claude-usage-panel
• License: MIT
• Homepage: https://fschmutz.github.io/claude-usage-panel/

Install and usage instructions live in the source repository linked above.