claude-usage-bar

KO | EN

gitlite — search

#python #hacktoberfest #ai #typescript #llm #go #android #rust #docker #macos #windows #vue #awesome-list #pytorch

claude-usage-bar

(★ 29)

A lightweight, native macOS menu bar app that shows your claude.ai usage limits at a glance — your 5-hour session window and your 7-day weekly window — without leaving the menu bar.

claude-usage-bar 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Claude Usage Bar

A lightweight, native **macOS menu bar app** that shows your [claude.ai](https://claude.ai) usage limits at a glance — your **5-hour session** window and your **7-day weekly** window — without leaving the menu bar.

![platform](https://img.shields.io/badge/platform-macOS%2012%2B-black)
![swift](https://img.shields.io/badge/Swift-5.9%2B-orange)
![frameworks](https://img.shields.io/badge/deps-Apple%20frameworks%20only-blue)
![license](https://img.shields.io/badge/license-MIT-green)

Two small Swift binaries compiled with `swiftc` — **no Electron, no Python, no third-party runtime, only Apple frameworks.**

> [!IMPORTANT]
> **Unofficial.** This is a community project, not affiliated with or endorsed by Anthropic. It reads the same private endpoint the claude.ai usage page uses, authenticated with **your own** session cookie. Use at your own discretion.

---

## Features

- ✳️ A **spark icon** in the menu bar showing your **current session usage %** once a cookie is set.
- 🎨 The menu bar icon and percentage **adapt to the menu bar background** (white on a dark bar, black on a light one) and are never tinted by usage level.
- 📊 A click-to-open popover with three sections:
  - **Current Session** — 5-hour window, with a progress bar and reset time.
  - **All Models** — 7-day weekly window, with a progress bar and reset time.
  - **Daily Routines** — session resets so far today and time until the next reset.
- 🟡🔴 In the popover, the percentage and progress bars are color-coded: **green** below 80%, **yellow** at 80%, **red** at 90%.
- ⌨️ Global hotkey **⌘U** toggles the popover from anywhere.
- 🔄 Refreshes automatically every **5 minutes**, when you open the popover, and via the **Refresh** button.
- 🔐 Your cookie is stored **only in the macOS Keychain** — never in a file or `UserDefaults`.
- 🚀 **Appears when the Claude desktop app launches** and **quits when you quit Claude** (you can also open or quit it manually).
- 🗑️ Built-in uninstaller (**Settings → Uninstall app**).

---

## Requirements

Everything below ships with macOS or is a one-line install — **no Homebrew or extra packages required**.

| Requirement | Notes |
|---|---|
| **macOS 12 Monterey or later** | Apple Silicon or Intel. |
| **Xcode Command Line Tools** | Provides `swiftc` to compile the app. Install with `xcode-select --install`. |
| **A claude.ai account** | Free, Pro, or Max. You paste your session cookie once (see below). |
| `openssl` + `security` | Both ship with macOS. The installer uses them to create a **local** self-signed certificate so the app has a stable identity and the Keychain stops re-prompting. |
| *(optional)* **Claude desktop app** | If installed, the menu bar app appears when you open Claude and quits when you quit it. Not required — you can launch it manually. |

---

## Install

```sh
git clone https://github.com/tmatteozzi/claude-usage-bar.git
cd claude-usage-bar/app
./install.sh
```

`install.sh` does everything in one run:

1. Compiles `ClaudeUsageBar.app` and the `ClaudeLauncher` helper with `swiftc` (deployment target macOS 12).
2. Creates a **local self-signed code-signing certificate** (`ClaudeUsageBar Self-Signed`) if one doesn't exist yet, and signs both binaries with it.
3. Copies both to `~/Applications/`.
4. Writes the LaunchAgent to `~/Library/LaunchAgents/` and loads it.

After it finishes, open the **Claude desktop app** (or launch `~/Applications/ClaudeUsageBar.app` directly) and the spark appears in your menu bar within a few seconds.

---

## First run — set your cookie

The app reads `https://claude.ai/api/organizations/{org}/usage` using your session cookie (the organization id is resolved automatically from the cookie, falling back to `GET /api/organizations`). The response is utilization percentages and reset times — claude.ai does not expose raw token counts here. To provide the cookie:

1. Open **claude.ai/settings/usage** in your browser.
2. Open **DevTools** (`⌘⌥I`) → the **Network** tab → **reload** the page.
3. Filter by **`usage`** and click that request.
4. Under **Request Headers**, copy the **full value** of the **`Cookie`** header.
5. In the app: **left-click the spark → Configure Cookie… → Paste → Save.**

The cookie is stored **only in your macOS Keychain**. It must include `sessionKey` (and usually `lastActiveOrg`). Cookies expire periodically — when usage stops updating, paste a fresh one the same way.

---

## Controls

| Action | Result |
|---|---|
| **Left-click** the icon | Open the usage popover |
| **Right-click** (or control-click) the icon | Menu: **View usage** / **Quit** |
| **⌘U** | Toggle the popover from any app |
| Popover → **Refresh** | Fetch fresh data now |
| Popover → **Settings** | **Reconfigure Cookie…** or **Uninstall app** |

---

## How it works

```
.
├── README.md
├── LICENSE
├── .gitignore
├── app/
│   ├── ClaudeUsageBar.swift   Main app: status item, popover (SwiftUI), usage fetch,
│   │                          Keychain, ⌘U hotkey (Carbon)
│   ├── ClaudeLauncher.swift   Background agent: launches the menu bar app when the
│   │                          Claude desktop app starts
│   ├── Info.plist             App bundle metadata (LSUIElement = menu-bar-only)
│   ├── SparkIcon.svg          Source icon
│   ├── SparkIcon.pdf          Vector icon bundled into the app (tints to the menu bar color)
│   ├── build.sh               Compiles + signs both binaries into app/build/
│   └── install.sh             build.sh + install to ~/Applications + LaunchAgent
└── LaunchAgents/
    └── com.claudeusagebar.launcher.plist   RunAtLoad + KeepAlive launcher agent
```

At login, only the silent launcher runs (no icon). When the Claude desktop app launches, the launcher starts the menu bar app; when you quit Claude, the menu bar app quits too.

---

## Privacy & security

- Your cookie lives **only in the macOS Keychain**, under a generic-password item. It is never written to disk, `UserDefaults`, logs, or anywhere else.
- The app talks **only to `claude.ai`**, sending your cookie exactly as your browser would, to read your own usage. No analytics, no telemetry, no other network calls.
- The self-signed certificate the installer creates is **local to your machine** and is used only to give the app a stable identity so the Keychain stops re-prompting. The uninstaller removes it.

---

## Updating

Pull the latest code and re-run the installer — it reuses the existing certificate, so there are no new Keychain prompts:

```sh
git pull
cd app && ./install.sh
```

---

## Uninstall

From the app: **left-click the spark → Settings → Uninstall app**. This removes the app, the launcher, the LaunchAgent, the stored cookie, and the signing certificate.

To do it manually:

```sh
launchctl unload ~/Library/LaunchAgents/com.claudeusagebar.launcher.plist
rm ~/Library/LaunchAgents/com.claudeusagebar.launcher.plist
rm -rf ~/Applications/ClaudeUsageBar.app ~/Applications/ClaudeLauncher
security delete-generic-password -s com.claudeusagebar.cookie -a claude-session-cookie
security delete-identity -c "ClaudeUsageBar Self-Signed"
```

---

## Troubleshooting

- **The icon shows no percentage / "No usage data".** Your cookie is missing or expired. Re-paste it (Configure Cookie…). When the cookie is rejected the popover shows an `Unauthorized (HTTP 401/403)` hint.
- **`swiftc: command not found`.** Install the Xcode Command Line Tools: `xcode-select --install`.
- **The build fails creating the signing certificate.** Make sure your login Keychain is unlocked, then re-run `./install.sh`. The installer signs the binaries with that certificate.
- **No menu bar icon after install.** Open the Claude desktop app (the launcher waits for it), or launch `~/Applications/ClaudeUsageBar.app` directly. The launcher logs to `/tmp/com.claudeusagebar.launcher.err.log`.

---

## Limitations

- Uses the **private** claude.ai usage endpoint (the one the website itself calls). It is not an official, documented API and may change without notice.
- The endpoint reports **utilization percentages and reset times**, not raw token counts — so the UI shows percentages.

---

## License

Released under the **MIT License** — see [LICENSE](LICENSE).

---

*Claude, Anthropic, and the Claude logo are trademarks of Anthropic. This project is independent and unofficial.*

claude-usage-bar

claude-usage-bar 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

claude-usage-bar

claude-usage-bar 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README