<p align="center"> <img src="logo.png" alt="Claude Usage Tracker" width="200"/> </p> <h1 align="center">Claude Usage Tracker</h1> <p align="center"> A native macOS menu bar app to monitor your Claude Code API usage in real-time. Track costs per month and per project with accurate, automatic updates. </p> <p align="center"> <img src="https://img.shields.io/badge/platform-macOS%2013.0+-blue" alt="Platform"/> <img src="https://img.shields.io/badge/Swift-5.9-orange" alt="Swift"/> <img src="https://img.shields.io/badge/license-Personal%20Use%20Only-green" alt="License"/> <img src="https://img.shields.io/badge/author-Sergio%20Ba%C3%B1uls-blue" alt="Author"/> </p>

✨ Features

🔌 LiteLLM API Integration - Connect to your company's LiteLLM API for exact usage data
- Real-time cost tracking from API (no calculations needed)
- Advanced Model Breakdown: Get exact costs for every model used (Claude, Gemini, Vertex AI, etc.)
- Today's spend monitoring & Budget reset date
- 🛡️ Anti-Flicker Protection: Smart algorithm prevents price drops when API glitches occur
- Full API Pagination Support: Automatically fetches all pages of data from API
- Clear data source indicator (API/Local)
🔔 Auto-Update Notifications - Never miss a new version
- Checks for updates on startup and every 2 hours
- Non-intrusive yellow banner when updates are available
- Orange dot indicator in menu bar (●)
- One-click access to release notes
🤖 Model Tracking - See exactly which AI models are driving your costs
🎯 Accurate Cost Tracking - Properly groups tool calls and calculates costs per conversation turn
📊 Real-time Monitoring - Current month cost visible in your menu bar
🔄 Smart Updates - Automatic silent updates every minute, manual refresh with visual feedback
📄 Pagination System - View 2 months at a time with elegant navigation controls
📅 Monthly Breakdown - Complete usage history organized by month
📁 Project Tracking - See which projects consume the most tokens
📈 Detailed Metrics - Token breakdown by type:
- Input tokens
- Cache creation (write) tokens
- Cache read tokens
- Output tokens
📤 CSV Export - Export your data in clean CSV format (by month, project, or model)
⚙️ Configurable Pricing - Adjust pricing for different Claude models and context windows
🌍 Multi-language - Switch between English 🇺🇸 and Spanish 🇪🇸
💱 Currency Conversion - Automatically shows costs in EUR (€) when Spanish is selected, using daily exchange rates
🖥️ Native macOS - Built with SwiftUI, lightweight and fast
🔒 Privacy-first - All usage data stays local (only fetches exchange rate once per day)*
🎨 Polished UI - Clean interface with smooth interactions and auto-close popover

*When using API integration, today's spend and budget info are fetched from your LiteLLM server

📸 Screenshots

Menu Bar

The app shows your current month's cost in the menu bar:

💰 $165.14

Main Panel - By Month

View detailed breakdown by month with token metrics:

📅 November 2025          $106.72
   • Input tokens: 41,666 → $0.12
   • Cache creation: 12,367,742 → $46.38
   • Cache read: 155,606,800 → $46.68
   • Output tokens: 902,055 → $13.53

📅 October 2025           $165.14
   • Input tokens: 108,448 → $0.33
   • Cache creation: 14,416,808 → $54.06
   • Cache read: 288,300,577 → $86.49
   • Output tokens: 1,617,636 → $24.26

──────────────────────────────────
TOTAL                     $271.86

Main Panel - By Project

See which projects cost the most:

📁 PROJECT-1              $98.45
📁 PROJECT-2              $73.21
📁 PROJECT-3              $42.18
📁 PROJECT-4              $12.34
...

Main Panel - By Model

Track costs by AI model used:

🤖 claude-3-5-sonnet-20241022    $145.32
🤖 gemini-2.0-flash-exp          $23.45
🤖 claude-3-opus-20240229        $18.76
🤖 gpt-4o                        $12.33
...

Settings Panel

Configure pricing and API integration:

LiteLLM API Key - Connect to your company's LiteLLM server for exact usage data
Pricing Configuration:
- Standard Context (≤ 200K tokens)
- Long Context (> 200K tokens)
- Customize rates for each token type (used for local calculation fallback)

🚀 Quick Start

Option 1: Install with Homebrew (Easiest)

# Add the tap
brew tap masorange/claudeusagetracker

# Install the app
brew install --cask masorange/claudeusagetracker/claudeusagetracker

Or install in one command:

brew install --cask masorange/claudeusagetracker/claudeusagetracker

Benefits:

✅ No need to run xattr manually - Homebrew automatically removes quarantine
✅ Easy updates: brew update && brew upgrade --cask masorange/claudeusagetracker/claudeusagetracker
✅ Clean uninstall: brew uninstall --cask masorange/claudeusagetracker/claudeusagetracker

To update to the latest version:

brew update && brew upgrade --cask masorange/claudeusagetracker/claudeusagetracker

Important: Always run brew update before brew upgrade to ensure Homebrew knows about the latest version. The command above does both in one line.

Option 2: Download Pre-built App

Download the latest .dmg file from the Releases page
Open the DMG file (double-click)
Drag ClaudeUsageTracker.app to the Applications folder shortcut
Remove macOS security block (required for unsigned apps):
```
xattr -cr /Applications/ClaudeUsageTracker.app
```
Right-click the app in Applications and select "Open" (first time only)
Look for the 💰 icon in your menu bar (top-right corner)

Note: Since this app is not signed with an Apple Developer certificate, macOS Gatekeeper will block it by default. The xattr command above removes this security block. You may still need to right-click and select "Open" the first time.

Option 3: Build from Source

Prerequisites

macOS 13.0 (Ventura) or later
Xcode Command Line Tools installed
Claude Code CLI with project history

Installation Steps

Clone the repository

git clone https://github.com/masorange/ClaudeUsageTracker.git
cd ClaudeUsageTracker

Build the app
```
chmod +x build.sh
./build.sh
```
Run the app
```
open ClaudeUsageTracker.app
```

(Optional) Install permanently

cp -r ClaudeUsageTracker.app /Applications/
open /Applications/ClaudeUsageTracker.app

📋 How It Works

Data Source

The app reads Claude Code's local project history files located at:

~/.claude/projects/

Each project directory contains .jsonl files with conversation history and token usage data.

Processing Logic

Scans all project directories recursively
Groups consecutive assistant messages into conversation "turns"
- Tool calls within the same turn (< 10 seconds apart) are counted as one billable event
- This prevents double-counting when Claude uses multiple tools
Parses usage data from each conversation turn
Calculates costs based on configurable pricing (defaults to Claude Sonnet 4.5):

Standard Context (≤ 200K tokens)

Input tokens: $3.00 per million
Cache creation (write): $3.75 per million (1.25× input rate)
Cache read: $0.30 per million (10% of input rate)
Output tokens: $15.00 per million

Long Context (> 200K tokens)

Input tokens: $6.00 per million
Cache creation (write): $7.50 per million (1.25× input rate)
Cache read: $0.60 per million (10% of input rate)
Output tokens: $22.50 per million

Groups data by month and project
Displays results in real-time

Why This Matters

Without proper turn grouping, tool-heavy conversations could be counted 2-3× higher than actual costs. This app accurately matches what you're billed by grouping all tool calls within a single conversation turn.

🎯 Usage

Menu Bar Icon

Shows current month's cost: 💰 $165.14 (or € when Spanish is selected)
Click to open the detailed panel
Updates silently every minute in the background
Click outside the panel to close it

Main Panel

Data Source Indicator:

🟢 API Data - Using LiteLLM API (exact costs from server)
🟠 Local Data - Using local file calculation (fallback mode)

Today's Spend (API mode only):

Shows your current day's usage
Displays budget reset date
Updates automatically with each refresh

Three tabs:

By Month 📅 - Monthly breakdown with detailed token metrics (paginated, 2 months per page)
By Project 📁 - Project-based cost analysis (always uses local data)
By Model 🤖 - Cost breakdown by specific model (Claude 3.5, Gemini Pro, etc.)

Controls:

📤 Export - Export current view to CSV file
⚙️ Settings - Configure API key and pricing
🇺🇸 / 🇪🇸 Language Selector - Switch between English and Spanish
🔄 Refresh - Manually update data (shows loading spinner)
✖️ Close - Exit the application
Last update - Timestamp of last data refresh (bottom)

Pagination (Monthly View)

When you have more than 2 months of data:

← Newer / Recientes - Go to more recent months
Page indicator - Shows current page (e.g., "1 / 3")
Older / Antiguos → - Go to older months
Total Cost - Always visible at the bottom, showing grand total

CSV Export

Export your data for analysis in Excel, Google Sheets, or other tools:

Switch to the view you want to export (By Month or By Project)
Click the 📤 Export button in the top-right
Choose where to save the file
The CSV will include:
- Month/Project name
- Token type (Input, Cache Creation, Cache Read, Output

ClaudeUsageTracker

Install / Use

README