ClaudeUsage

KO | EN

gitlite — search

#python #hacktoberfest #golang #android #machine-learning #rust #docker #nodejs #awesome #awesome-list #pytorch #security #ios #open-source

(★ 12)

macOS menu bar app to monitor Claude Code API usage limits

ClaudeUsage Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🧠 Claude Usage

A lightweight macOS menu bar app that monitors your [Claude Code](https://docs.anthropic.com/en/docs/claude-code) API usage limits in real time.

![macOS 13+](https://img.shields.io/badge/macOS-13.0%2B-blue?logo=apple)
![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138?logo=swift&logoColor=white)
![License MIT](https://img.shields.io/badge/license-MIT-green)

---

## Features

| Feature | Description |
|---------|-------------|
| **Menu bar indicator** | Always-visible usage percentage with brain icon |
| **Session & weekly limits** | Track 5-hour session and 7-day usage windows (All Models + Sonnet) |
| **Configurable notifications** | Usage threshold alerts on/off (50–95%), before-reset reminders (15/30/60 min), on-reset alerts |
| **Auto-refresh** | Configurable polling interval (1 / 3 / 5 / 10 min) + instant refresh on click |
| **Launch at login** | Auto-start with macOS |
| **Zero config** | Reads credentials from Claude Code CLI automatically |

## Install

### Option 1: Download Release

1. Go to [**Releases**](../../releases/latest)
2. Download `ClaudeUsage.zip`
3. Unzip and drag `Claude Usage.app` to `/Applications`
4. Launch from Applications or Spotlight (`Cmd + Space` → "Claude Usage")

### Option 2: Build from Source

```bash
git clone https://github.com/DaniilKimlb/ClaudeUsage.git
cd ClaudeUsage
brew install xcodegen      # if not installed
xcodegen generate
xcodebuild -scheme ClaudeCodeUsage -configuration Release build
```

The built `.app` will be in `~/Library/Developer/Xcode/DerivedData/.../Build/Products/Release/`.

## Prerequisites

- **macOS 13.0** or later
- [**Claude Code CLI**](https://docs.anthropic.com/en/docs/claude-code) installed and signed in:
  ```bash
  npm install -g @anthropic-ai/claude-code
  claude
  ```

## How It Works

1. Reads your OAuth credentials from Claude Code CLI (Keychain or `~/.claude/.credentials.json`)
2. Queries the [Anthropic usage API](https://api.anthropic.com/api/oauth/usage) to get current limits
3. Displays session (5-hour) and weekly (7-day) usage in the menu bar popover
4. Sends macOS notifications when thresholds are reached or limits reset

## Settings

Click the gear icon in the popover to configure:

- **Usage threshold alert** — on/off + slider (50–95%)
- **Notify before reset** — on/off + time picker (15 / 30 / 60 min)
- **Notify on limit reset** — on/off
- **Auto-refresh interval** — 1 / 3 / 5 / 10 minutes
- **Launch at login** — on/off

All settings persist across app restarts via `UserDefaults`.

## macOS Permissions

Claude Usage is a lightweight, non-sandboxed menu bar app. Here's what it accesses and why:

### Keychain Access (prompted by macOS)

Claude Code CLI stores your OAuth credentials in the macOS Keychain under `"Claude Code-credentials"`. Claude Usage reads this entry to authenticate with the Anthropic API.

**Why you see a Keychain prompt:** macOS asks for permission the first time Claude Usage reads the credential. This is standard macOS security behavior.

**How to prevent repeated Keychain prompts:**

1. Open **Keychain Access.app** → search for `"Claude Code-credentials"`
2. Double-click the item → go to **Access Control** tab
3. Click **+** and add `Claude Usage.app` under "Always allow access by these applications"
4. Save and relaunch Claude Usage

> Prefer adding just Claude Usage — avoid "Allow all applications" unless you specifically want that.

### Notifications (prompted on first launch)

Claude Usage requests notification permission to send usage threshold alerts. You can manage this in **System Settings → Notifications → Claude Usage**.

### Network Access

The app makes HTTPS requests to:
- `api.anthropic.com` — to fetch usage data
- `platform.claude.com` — to refresh expired OAuth tokens

No other network requests are made.

### Files & Folders

If credentials aren't found in Keychain, the app falls back to reading `~/.claude/.credentials.json` (the file-based credential store used by Claude Code CLI).

### What We Do NOT Request

| Permission | Required? |
|-----------|-----------|
| Full Disk Access | No |
| Screen Recording | No |
| Accessibility | No |
| Automation | No |
| Camera / Microphone | No |
| Location | No |

No passwords are stored by the app. OAuth tokens are read from Claude Code CLI's existing credential stores (Keychain or credentials file). No browser cookies are accessed.

## Tech Stack

- **SwiftUI** + **AppKit** (NSStatusItem for menu bar)
- **Combine** for reactive data flow
- **UserNotifications** for native macOS alerts
- **ServiceManagement** for launch-at-login
- **No external dependencies** — pure Apple frameworks

## Troubleshooting

| Problem | Solution |
|---------|----------|
| "Claude Code not found" | Install Claude Code CLI and run `claude` to sign in |
| Keychain prompt on every launch | Add Claude Usage to Keychain item's Access Control (see above) |
| No notifications | Check System Settings → Notifications → Claude Usage is enabled |
| Menu bar shows "err" | Check network connection; click to see full error in popover |
| App won't open (macOS Gatekeeper) | Right-click → Open, or: System Settings → Privacy & Security → Open Anyway |

## Contributing

PRs welcome! Feel free to open issues for bugs or feature requests.

## License

MIT — see [LICENSE](LICENSE) for details.

ClaudeUsage

ClaudeUsage Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ClaudeUsage

ClaudeUsage Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README