Claude God
Monitor your Claude AI usage from the macOS menu bar.
Real-time quotas, cost analytics, burn rate prediction, project breakdown.
Free, open source, zero dependencies.
Download .dmg ·
Website ·
Changelog
---
## Features
| | Feature | Description |
|---|---|---|
| **Quotas** | Progress bars | Animated bars for session (5h), weekly, Sonnet & Opus quotas |
| | Dynamic icon | Menu bar icon turns green/orange/red based on worst quota |
| | Live countdown | Real-time timer showing when quotas reset |
| | Burn rate | Predicts when you'll hit the limit based on current velocity |
| | Model advisor | Smart tips when quota imbalance is detected |
| **Analytics** | Cost tracking | Daily, weekly, monthly cost breakdown from JSONL session files |
| | Project breakdown | Per-project cost and session count |
| | Session history | Recent conversations with topic, duration, cost, model |
| | Sparkline chart | Interactive usage trend (7/14/30 days) with hover tooltips |
| | Model breakdown | Per-model cost and token usage with totals |
| | Daily budget | Set a $/day target with progress tracking |
| | Export CSV | Save daily cost & token data as CSV |
| | Copy stats | One-click copy of formatted stats to clipboard |
| **Live** | Active session | Detects when Claude Code is running (green dot) |
| | Auto-credentials | File watcher auto-detects `claude login` |
| | Reset notification | Get notified when quotas reset |
| **Settings** | Auto-refresh | Configurable interval (1, 2, 5, 10 min) |
| | Menu bar modes | Icon only, Session %, Timer, All quotas |
| | Compact mode | Minimal UI showing just percentages |
| | Notifications | Alert when usage exceeds configurable threshold |
| | Launch at login | Start automatically with macOS |
| **Extensions** | Plugin marketplace | Browse, search, and install Claude Code plugins directly from the app |
| | Category filter | Filter plugins by category (Development, Productivity, Database, etc.) |
| | Install counts | See plugin popularity with download stats |
| | Manage plugins | Toggle enabled/disabled, uninstall, check for updates |
| | Plugin UI | Installed plugins with custom UI (e.g. claude-mem) open inline detail views |
| **Design** | shadcn/ui style | Flat, minimal, bordered cards with hover effects |
| | Dark & Light | Adapts to system appearance automatically |
| | Accessibility | VoiceOver labels on all interactive elements |
> **No API key needed.** Uses your existing `claude login` credentials. Works with Pro & Max plans. Completely free.
---
## Quick Start
### Homebrew (recommended)
```bash
brew tap lcharvol/tap
brew install --cask claude-god
```
### Manual
```bash
# 1. Download & install
open https://github.com/Lcharvol/Claude-God/releases/latest/download/ClaudeGod.dmg
# 2. Allow unsigned app (required once)
xattr -cr /Applications/Claude\ God.app
```
### Then
```bash
# Make sure you're logged in
claude login
# Launch — a "C" icon appears in the menu bar, press ⌥⌘C to toggle
open /Applications/Claude\ God.app
```
---
## How It Works
**Quotas** — The app reads your OAuth credentials from `claude login` (Keychain or `~/.claude/.credentials.json`) and calls:
```
GET https://api.anthropic.com/api/oauth/usage
Authorization: Bearer
anthropic-beta: oauth-2025-04-20
```
Returns utilization for each quota window (`five_hour`, `seven_day`, `seven_day_sonnet`, `seven_day_opus`). Tokens are refreshed automatically.
**Cost Analytics** — Parses all `~/.claude/projects/**/*.jsonl` session files to calculate costs per model using Anthropic's published pricing.
---
## Build from Source
```bash
git clone https://github.com/Lcharvol/Claude-God.git
cd Claude-God
brew install xcodegen # one time
make build # or: make open (Xcode)
```
See [`Makefile`](Makefile) for all commands: `build`, `run`, `dmg`, `clean`.
## Project Structure
```
Sources/
├── ClaudeUsageApp.swift # Entry point, MenuBarExtra
├── UsageManager.swift # OAuth, auto-refresh, notifications, budget, active session
├── AuthManager.swift # Credential loading, token refresh, file watcher
├── UpdateChecker.swift # GitHub releases auto-update
├── HotkeyManager.swift # Global ⌥⌘C hotkey (Carbon API)
├── AppShortcuts.swift # Shortcuts.app intents (Get Usage, Get Cost, Refresh)
├── MenuBarView.swift # UI: cards, stats, settings, heatmap, shadcn components
├── SessionAnalyzer.swift # JSONL parser, cost calculator, efficiency metrics
└── Assets.xcassets/ # App icon
Widget/
└── ClaudeGodWidget.swift # WidgetKit — desktop quota gauges
```
**Zero external dependencies.** Foundation + SwiftUI + Combine + Security + UserNotifications + ServiceManagement.
## Releasing
```bash
git tag v2.8.0 && git push origin v2.8.0
# GitHub Actions builds the .dmg automatically
```
## Changelog
### v2.23.4
- **Fixed**: Repeated "Claude God wants to use your confidential information stored in `Claude Code-credentials-XXXXXXXX`" prompt — newer Claude Code versions write credentials under suffixed service names, and the per-entry data fetch in `loadBestKeychainEntryWithPrefix` used `SecItemCopyMatching + kSecReturnData`, which prompts on every read. The fetch now reuses the existing `security find-generic-password` helper with the exact service name discovered from the non-prompting list query, so the dialog loop disappears ([#30](https://github.com/Lcharvol/Claude-God/issues/30), [#31](https://github.com/Lcharvol/Claude-God/pull/31), thanks @nairdaleo)
### v2.23.3
- **Fixed**: No more "Claude God wants to access the keychain" prompt for the common case — v2.23.2's fallback hit the Security framework API directly (which prompts the first time an ad-hoc-signed app reads an item it didn't create). Now tries `security find-generic-password -a $USER` as a second non-prompting fast path before the API; the scan only runs for unusual multi-account layouts
### v2.23.2
- **Fixed**: PR #27 Keychain fallback actually works now — the scan called `SecItemCopyMatching` with an attribute combination (`kSecReturnAttributes + kSecReturnData + kSecMatchLimitAll`) that returns `errSecParam (-50)` on the legacy login keychain, so it bailed out before reading anything. Now lists refs+attributes first, then fetches each item's data with a per-item query, so users with multiple `Claude Code-credentials` entries (Claude Code stores `account=unknown` next to `account=`) finally connect
### v2.23.1
- **Fixed**: Embedded `claude auth login` no longer crashes the app — PTY slave FD was being closed twice (after the first close, the OS reused that FD slot for a guarded keychain socket, then the handle's dealloc triggered `EXC_GUARD`); slave handle now uses `closeOnDealloc: false` ([#26](https://github.com/Lcharvol/Claude-God/issues/26), [#27](https://github.com/Lcharvol/Claude-God/pull/27), thanks @nairdaleo)
- **Fixed**: Credentials detected when only per-project Keychain entries exist — newer Claude Code writes suffixed entries (`Claude Code-credentials/path/...`) and may leave the base entry stale, so signed-in users appeared "Not connected"; `AuthManager` now scans all `Claude Code-credentials*` items as a fallback
- **Fixed**: Popover only grows downward when resizing — new `WindowTopAnchor` pins the top edge to the status bar item in Release/Homebrew builds (was resizing from the center)
### v2.23.0
- **New**: Extra Usage (dollar budget) is now a first-class quota across the app — surfaced as a % in every menu bar mode (including `E X%` in "All" mode), selectable as a ring in Icon+ Rings, drives icon warning/critical colors, and fires standard + custom usage alerts. The popover's Extra Usage card gains a color-coded progress bar when a monthly limit is set ([#25](https://github.com/Lcharvol/Claude-God/pull/25), thanks @ecoffey)
### v2.22.2
- **Changed**: Peak hours window updated to Mon–Fri 5am–11am PT to match Anthropic's actual throttling band for 5-hour session limits (was 7am–5pm PT) ([#24](https://github.com/Lcharvol/Claude-God/pull/24), thanks @pieropalevsky)
- **Refactored**: Tooltips derive from a single `peakHoursDescription` source-of-truth so future policy changes touch one constant instead of three sites
### v2.22.1
- **Fixed**: OAuth token self-refresh — now sends `application/x-www-form-urlencoded` per RFC 6749, ending the HTTP 400 loop on silent refresh ([#21](https://github.com/Lcharvol/Claude-God/issues/21), [#22](https://github.com/Lcharvol/Claude-God/pull/22))
- **Fixed**: `claude` binary resolution — falls back to `$SHELL -l -c "which claude"` so nvm / fnm / volta / pnpm installs are found
- **Fixed**: Auto-recovery after manual `claude auth login` — 10s background poller picks up Keychain-only credential writes without needing Sign In
### v2.22.0
- **New**: Rings menu bar mode — Apple Watch-style concentric activity rings for up to 3 quotas, configurable picker + live preview, optional Timer ring ([#20](https://github.com/Lcharvol/Claude-God/pull/20))
### v2.21.1
- **Fixed**: Drastic energy savings — App Nap re-enabled, adaptive countdown, slower active-session polling, JSONL scan deferred to popover open ([#14](https://github.com/Lcharvol/Claude-God/issues/14))
- **Fixed**: Widget extension now registers — added missing `NSExtensionPointIdentifier` ([#13](https://github.com/Lcharvol/Claude-God/issues/13))
- **Fixed**: Resizable popover actually responds to drag — visible grip handle replaces the broken NSWindow wiring
### v2.21.0
- **New**: Session+Week menu bar mode — session %, reset countdown, and weekly % at a glance ([#15](https://github.com/Lcharvol/Claude-God/issues/15))
- **New**: Resizable window with persisted height
- **New**: Extra usage balance card + Claude Design quota row
- **New**: Sign In button + opt-in auto-reconnect when OAuth token expires
- **Fixed**: Usage tab flicker on expired token, long reset times shown as days/hours
### v2.20.4
- **Fixed**: Hardened refresh pipeline — every exit path clears loading state, credential reload timeouts, backoff counter auto-resets
### v2.20.3
- **Fixed**: Respect `Retry-After` header on 429, progressive backoff, token expiry pre-flight, Keychain fallback for credentials
### v2.20.2
- **Fixed**: App no longer gets stuck on "Rate limited" screen after `claude login` ([#5](https://github.com/Lcharvol/Claude-God/issues/5))
- **Fixed**: Credential changes now trigger auto-refresh even when an error is displayed
### v2.20.1
- **Fixed**: Refresh no longer gets stuck — cancellable fetches, stale response detection, centralized state reset
- **New**: Peak / off-peak indicator with countdown to transition
### v2.19.0
- **Perf**: JSONL parsing without Data→String roundtrip, SQLite 9→4 queries, widget skip unchanged, keychain off main thread
### v2.18.0
- **New**: GitHub, swift-lsp, code-review, code-simplifier, context7, playwright plugin detail views (9 total)
- **Fixed**: Menu bar icon contrast, font sizes +1pt, wider window
### v2.17.0
- **New**: Superpowers plugin UI — browse skills, view plans with progress, design specs
- **New**: Frontend Design plugin UI — design principles, aesthetic tones, anti-patterns, cookbook link
### v2.16.0
- **New**: Extensions tab with plugin marketplace — browse, install, and manage Claude Code plugins directly from the app
- **New**: Featured plugin cards for plugins with custom UI (claude-mem opens inline Memory panel)
### v2.15.0
- **Fixed**: Memory tab now reads correct claude-mem schema (`observations` table)
- **New**: Activity timeline, project summaries, Markdown export, delete observations, open files in Finder
### v2.14.0
- **New**: Memory tab — browse claude-mem persistent memories with search, project filter, and install guide
### v2.13.1
- **Fix**: OAuth token refresh no longer persists tokens — prevents daily 401 errors
### v2.13.0
- **Perf**: Single JSON decode per JSONL line, direct Data line splitting, single-pass file traversal, binary search for ROI matching
### v2.12.0
- **Improved**: Logging, error handling, forecasting, and exports
### v2.11.0
- **New**: ROI tab — correlates git commits with Claude sessions (cost/commit, per-project, per-model, 30-day trend)
### v2.10.0
- **New**: Updated model pricing, landing page SEO, download counter
- **Fix**: Project cost truncation, mobile layout, 429 handling
### v2.9.0
- **Fix**: Token refresh race condition, notification spam, reset timer, CSV export, duplicate alert rules
### v2.8.0
- **New**: Desktop widget, usage heatmap, live session cost, per-project budgets, Shortcuts.app, multi-account, custom alerts
[Full changelog →](CHANGELOG.md)
## License
[MIT](LICENSE)