# Claude Usage Panel

> See your Claude Code plan usage everywhere — GNOME top bar, macOS menu bar, a status line under the Claude Code prompt, and a get_usage MCP tool for Claude Code + Cursor. Session, weekly & per-model (Fable/Opus) limits from the official usage API. One-line install.

- **Type:** MCP server
- **Install:** `agentstack add mcp-fschmutz-claude-usage-panel`
- **Verified:** Pending review
- **Seller:** [fschmutz](https://agentstack.voostack.com/s/fschmutz)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fschmutz](https://github.com/fschmutz)
- **Source:** https://github.com/fschmutz/claude-usage-panel
- **Website:** https://fschmutz.github.io/claude-usage-panel/

## Install

```sh
agentstack add mcp-fschmutz-claude-usage-panel
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
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 →](https://fschmutz.github.io/claude-usage-panel/#install)**

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:

```text
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`](https://github.com/ryoppippi/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:

```text
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](https://github.com/fschmutz)
- **Source:** [fschmutz/claude-usage-panel](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-fschmutz-claude-usage-panel
- Seller: https://agentstack.voostack.com/s/fschmutz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.