README.md

June 15, 2026 · View on GitHub

Release macOS 13+ Swift 5.9 MIT License CI

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.

Usage — quota cards with progress bars    Analytics — cost breakdown, sparkline, models

Timeline — session history with topics and costs    ROI — return on investment analysis

Extensions — discover and install plugins    Extensions — manage installed plugins

Download .dmg  ·  Website  ·  Changelog

Features

FeatureDescription
QuotasProgress barsAnimated bars for session (5h), weekly, Sonnet & Opus quotas
Dynamic iconMenu bar icon turns green/orange/red based on worst quota
Live countdownReal-time timer showing when quotas reset
Burn ratePredicts when you'll hit the limit based on current velocity
Model advisorSmart tips when quota imbalance is detected
AnalyticsCost trackingDaily, weekly, monthly cost breakdown from JSONL session files
Project breakdownPer-project cost and session count
Session historyRecent conversations with topic, duration, cost, model
Sparkline chartInteractive usage trend (7/14/30 days) with hover tooltips
Model breakdownPer-model cost and token usage with totals
Daily budgetSet a $/day target with progress tracking
Export CSVSave daily cost & token data as CSV
Copy statsOne-click copy of formatted stats to clipboard
LiveActive sessionDetects when Claude Code is running (green dot)
Auto-credentialsFile watcher auto-detects claude login
Reset notificationGet notified when quotas reset
SettingsAuto-refreshConfigurable interval (1, 2, 5, 10 min)
Menu bar modesIcon only, Session %, Timer, All quotas
Compact modeMinimal UI showing just percentages
NotificationsAlert when usage exceeds configurable threshold
Launch at loginStart automatically with macOS
ExtensionsPlugin marketplaceBrowse, search, and install Claude Code plugins directly from the app
Category filterFilter plugins by category (Development, Productivity, Database, etc.)
Install countsSee plugin popularity with download stats
Manage pluginsToggle enabled/disabled, uninstall, check for updates
Plugin UIInstalled plugins with custom UI (e.g. claude-mem) open inline detail views
Designshadcn/ui styleFlat, minimal, bordered cards with hover effects
Dark & LightAdapts to system appearance automatically
AccessibilityVoiceOver labels on all interactive elements

No API key needed. Uses your existing claude login credentials. Works with Pro & Max plans. Completely free.

Quick Start

brew tap lcharvol/tap
brew install --cask claude-god

Manual

# 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

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

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

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, #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=<user>) 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, #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, 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, 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, #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)

v2.21.1

  • Fixed: Drastic energy savings — App Nap re-enabled, adaptive countdown, slower active-session polling, JSONL scan deferred to popover open (#14)
  • Fixed: Widget extension now registers — added missing NSExtensionPointIdentifier (#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)
  • 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)
  • 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 →

License

MIT