Merge pull request #4 from Priyans-hu/feat/heatmap-and-notifications

Usage heatmap and rate limit notifications

Author: Priyans-hu

README.md

@@ -1,23 +1,24 @@
 # TokenMeter
 
-macOS menu bar app for visualizing Claude Code token usage and costs. Built with SwiftUI.
+macOS menu bar app for tracking Claude Code usage, rate limits, and costs. Built with SwiftUI.
 
-Parses Claude Code's local conversation data to show real-time usage stats — no API keys or external tools needed.
+Reads Claude Code's OAuth token from Keychain for real rate limit data, and parses local JSONL files for cost and usage analytics.
 
 ![macOS](https://img.shields.io/badge/macOS_14+-000?logo=apple&logoColor=white)
 ![SwiftUI](https://img.shields.io/badge/SwiftUI-007AFF?logo=swift&logoColor=white)
 
 ## Features
 
-- **Menu bar app** — lives in menu bar, no dock icon, works in fullscreen
-- **Native macOS** — built with SwiftUI and Swift Charts
-- **Rate limit tracking** — 5-hour session and weekly output token usage with plan-based limits
-- **Cost summary** — today / this week / this month (calculated with embedded pricing)
+- **Real rate limits** — fetches actual utilization from Anthropic API via Claude Code's OAuth token
+- **Rate limit notifications** — macOS alerts when session or weekly usage hits 80%
+- **Usage heatmap** — hour-by-day grid showing when you're most active (7/14/30 day range)
+- **Hover details** — token breakdown (input/output) appears on hover over rate limit bars
+- **Cost summary** — today / this week / this month (API-equivalent pricing)
 - **Daily cost chart** — bar chart with 7/14/30 day range
 - **Model breakdown** — donut chart showing per-model usage (Opus, Sonnet, Haiku)
-- **Plan selection** — Pro / Max 5x / Max 20x for estimated rate limits
+- **Menu bar app** — lives in menu bar, no dock icon, works in fullscreen
 - **Auto-refresh** — every 5 minutes (configurable)
-- **Zero dependencies** — parses `~/.claude/` JSONL files directly, no external tools required
+- **Fallback mode** — if Keychain/API unavailable, uses local JSONL estimates with plan selection
 
 ## Installation
 
@@ -58,21 +59,26 @@ cp .build/release/TokenMeter /Applications/TokenMeter.app/Contents/MacOS/TokenMe
 ### Prerequisites
 
 - macOS 14 (Sonoma) or later
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and used (generates the local data TokenMeter reads)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and used
 
 ## How It Works
 
-TokenMeter reads Claude Code's local JSONL files from `~/.claude/projects/`:
+### Rate Limits (real data)
+TokenMeter reads Claude Code's OAuth token from the macOS Keychain and calls `api.anthropic.com/api/oauth/usage` to get real utilization percentages and reset times. On first launch, macOS will ask you to allow Keychain access — click "Always Allow".
 
-1. **Daily usage** — scans all conversation JSONL files, groups by date, calculates token costs using embedded model pricing
-2. **Rate limits** — tracks output tokens in the last 5 hours (session) and 7 days (weekly), shows progress against estimated plan limits
-3. **Model breakdown** — identifies which models (Opus, Sonnet, Haiku) are being used and their relative costs
+### Usage Analytics (local data)
+Parses JSONL files from `~/.claude/projects/` and `~/.config/claude/projects/`:
+- **Daily costs** — groups by date, calculates using embedded model pricing
+- **Hourly heatmap** — groups by hour-of-day per date for activity patterns
+- **Model breakdown** — per-model token and cost breakdown
+- Deduplicates by `requestId` and filters `<synthetic>` entries
 
-No API keys, no external tools, no cloud services. Everything is local.
+### Notifications
+Sends macOS notifications when rate limit utilization reaches 80% (session or weekly). Throttled to once per hour per window. Toggle in Settings.
 
 ### Pricing
 
-Costs are calculated using Anthropic's published API-equivalent pricing (per million tokens):
+Costs are calculated using API-equivalent pricing (per million tokens):
 
 | Model | Input | Output | Cache Write | Cache Read |
 |-------|-------|--------|-------------|------------|
@@ -88,28 +94,33 @@ Costs are calculated using Anthropic's published API-equivalent pricing (per mil
 ```
 TokenMeter/
 ├── TokenMeterApp.swift              # App entry with MenuBarExtra
-├── UsageViewModel.swift             # State management, timer, caching
+├── UsageViewModel.swift             # State, timer, caching, notifications
 ├── Models/
 │   └── UsageSummary.swift           # Data models + ClaudePlan enum
 ├── Services/
 │   ├── NativeUsageParser.swift      # JSONL parser + pricing engine
+│   ├── UsageAPIService.swift        # Keychain + Anthropic API client
 │   └── UpdateChecker.swift          # GitHub releases checker
 └── Views/
     ├── DashboardView.swift          # Main popover container
-    ├── RateLimitView.swift          # Progress bar with plan limits
+    ├── RateLimitView.swift          # Progress bar with hover details
+    ├── UsageHeatmapView.swift       # Hour-by-day activity heatmap
     ├── CostSummaryView.swift        # Today/week/month cost cards
     ├── DailyChartView.swift         # Swift Charts bar chart
     ├── ModelBreakdownView.swift     # Swift Charts donut chart
-    └── SettingsView.swift           # Plan picker, refresh interval
+    └── SettingsView.swift           # Plan, notifications, refresh interval
 ```
 
 ```
 Data Flow:
-  ~/.claude/projects/*.jsonl  ──>  NativeUsageParser  ──>  DailyUsage + RateLimits
-                                        │
+  Keychain OAuth  ──>  UsageAPIService  ──>  Real rate limit %
+                                │
+  ~/.claude/*.jsonl  ──>  NativeUsageParser  ──>  Costs + Hourly + Tokens
+                                │
   Timer (5min)  ──>  UsageViewModel  ──>  UsageSummary  ──>  SwiftUI Views
-                          │
-                          └──>  UserDefaults cache (instant reopen)
+                          │                                      │
+                          ├──>  UserDefaults cache               └──>  Notifications (≥80%)
+                          └──>  UNUserNotificationCenter
 ```
 
 ## License

TokenMeter/TokenMeter/Models/UsageSummary.swift

@@ -2,6 +2,7 @@ import Foundation
 
 struct UsageSummary: Codable {
     let daily: [DailyUsage]
+    let hourly: [HourlyUsage]
     let todayCost: Double
     let weekCost: Double
     let monthCost: Double
@@ -68,6 +69,17 @@ struct WindowInfo: Codable {
     let windowHours: UInt32
 }
 
+// MARK: - Hourly Usage (for heatmap)
+
+struct HourlyUsage: Codable, Identifiable {
+    var id: String { "\(date)-\(hour)" }
+
+    let date: String    // yyyy-MM-dd
+    let hour: Int       // 0-23
+    let outputTokens: UInt64
+    let requestCount: Int
+}
+
 // MARK: - Claude Plan
 
 enum ClaudePlan: String, CaseIterable, Codable {

TokenMeter/TokenMeter/Resources/AppIcon.icns

@@ -2,6 +2,7 @@ import Foundation
 
 struct ParseResult {
     let daily: [DailyUsage]
+    let hourly: [HourlyUsage]
     let rateLimits: RateLimitInfo
 }
 
@@ -30,9 +31,10 @@ struct NativeUsageParser {
         let entries = deduplicateByRequestId(rawEntries)
 
         let daily = aggregateDailyUsage(entries: entries, since: cutoff)
+        let hourly = aggregateHourlyUsage(entries: entries, since: cutoff)
         let rateLimits = computeRateLimits(entries: entries, now: now)
 
-        return ParseResult(daily: daily, rateLimits: rateLimits)
+        return ParseResult(daily: daily, hourly: hourly, rateLimits: rateLimits)
     }
 
     // MARK: - File Scanning
@@ -181,6 +183,36 @@ struct NativeUsageParser {
         }.sorted { $0.date < $1.date }
     }
 
+    // MARK: - Hourly Aggregation
+
+    private func aggregateHourlyUsage(entries: [ParsedEntry], since: Date) -> [HourlyUsage] {
+        let dateFormatter = DateFormatter()
+        dateFormatter.dateFormat = "yyyy-MM-dd"
+        let calendar = Calendar.current
+
+        // key = "yyyy-MM-dd-HH"
+        var hourMap: [String: (outputTokens: UInt64, requestCount: Int)] = [:]
+
+        for entry in entries {
+            guard entry.timestamp >= since else { continue }
+            let dateStr = dateFormatter.string(from: entry.timestamp)
+            let hour = calendar.component(.hour, from: entry.timestamp)
+            let key = "\(dateStr)-\(hour)"
+
+            var acc = hourMap[key] ?? (outputTokens: 0, requestCount: 0)
+            acc.outputTokens += entry.outputTokens
+            acc.requestCount += 1
+            hourMap[key] = acc
+        }
+
+        return hourMap.map { (key, acc) in
+            let parts = key.split(separator: "-")
+            let date = parts.prefix(3).joined(separator: "-")
+            let hour = Int(parts.last!) ?? 0
+            return HourlyUsage(date: date, hour: hour, outputTokens: acc.outputTokens, requestCount: acc.requestCount)
+        }.sorted { $0.date == $1.date ? $0.hour < $1.hour : $0.date < $1.date }
+    }
+
     // MARK: - Rate Limits
 
     private func computeRateLimits(entries: [ParsedEntry], now: Date) -> RateLimitInfo {

TokenMeter/TokenMeter/Services/NativeUsageParser.swift

@@ -1,5 +1,6 @@
 import Foundation
 import Combine
+import UserNotifications
 
 @MainActor
 final class UsageViewModel: ObservableObject {
@@ -16,14 +17,22 @@ final class UsageViewModel: ObservableObject {
     private let apiService = UsageAPIService()
     private let updateChecker = UpdateChecker(currentVersion: Bundle.main.appVersion)
 
+    @Published var notificationsEnabled: Bool {
+        didSet { UserDefaults.standard.set(notificationsEnabled, forKey: "notificationsEnabled") }
+    }
+
     private var refreshTimer: Timer?
     private var refreshInterval: TimeInterval = 300
+    private var lastSessionNotification: Date?
+    private var lastWeeklyNotification: Date?
 
     init() {
         let planStr = UserDefaults.standard.string(forKey: "claudePlan") ?? "pro"
         selectedPlan = ClaudePlan(rawValue: planStr) ?? .pro
+        notificationsEnabled = UserDefaults.standard.object(forKey: "notificationsEnabled") as? Bool ?? true
 
         loadCachedData()
+        requestNotificationPermission()
         Task {
             await refresh()
             await checkForUpdates()
@@ -47,9 +56,10 @@ final class UsageViewModel: ObservableObject {
         rateLimits.apiSession = apiUsage?.fiveHour
         rateLimits.apiWeekly = apiUsage?.sevenDay
 
-        let summary = aggregateSummary(daily: result.daily, rateLimits: rateLimits)
+        let summary = aggregateSummary(daily: result.daily, hourly: result.hourly, rateLimits: rateLimits)
         self.summary = summary
         saveCachedData(summary)
+        checkRateLimitAlerts(rateLimits)
 
         isLoading = false
     }
@@ -64,7 +74,7 @@ final class UsageViewModel: ObservableObject {
 
     // MARK: - Private
 
-    private func aggregateSummary(daily: [DailyUsage], rateLimits: RateLimitInfo) -> UsageSummary {
+    private func aggregateSummary(daily: [DailyUsage], hourly: [HourlyUsage], rateLimits: RateLimitInfo) -> UsageSummary {
         let formatter = DateFormatter()
         formatter.dateFormat = "yyyy-MM-dd"
         let todayStr = formatter.string(from: Date())
@@ -96,6 +106,7 @@ final class UsageViewModel: ObservableObject {
 
         return UsageSummary(
             daily: daily,
+            hourly: hourly,
             todayCost: todayCost,
             weekCost: weekCost,
             monthCost: monthCost,
@@ -124,6 +135,52 @@ final class UsageViewModel: ObservableObject {
         guard let data = try? JSONEncoder().encode(summary) else { return }
         UserDefaults.standard.set(data, forKey: "cachedSummary")
     }
+
+    // MARK: - Notifications
+
+    private func requestNotificationPermission() {
+        UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound]) { _, _ in }
+    }
+
+    private func checkRateLimitAlerts(_ rateLimits: RateLimitInfo) {
+        guard notificationsEnabled else { return }
+        let now = Date()
+
+        if let api = rateLimits.apiSession, api.utilization >= 80 {
+            if lastSessionNotification == nil || now.timeIntervalSince(lastSessionNotification!) > 3600 {
+                sendNotification(
+                    title: "Session limit at \(Int(api.utilization))%",
+                    body: "Your 5-hour rate limit is running low."
+                )
+                lastSessionNotification = now
+            }
+        }
+
+        if let api = rateLimits.apiWeekly, api.utilization >= 80 {
+            if lastWeeklyNotification == nil || now.timeIntervalSince(lastWeeklyNotification!) > 3600 {
+                sendNotification(
+                    title: "Weekly limit at \(Int(api.utilization))%",
+                    body: "Your 7-day rate limit is running low."
+                )
+                lastWeeklyNotification = now
+            }
+        }
+    }
+
+    private func sendNotification(title: String, body: String) {
+        let content = UNMutableNotificationContent()
+        content.title = "TokenMeter"
+        content.subtitle = title
+        content.body = body
+        content.sound = .default
+
+        let request = UNNotificationRequest(
+            identifier: UUID().uuidString,
+            content: content,
+            trigger: nil
+        )
+        UNUserNotificationCenter.current().add(request)
+    }
 }
 
 // MARK: - Bundle Extension

TokenMeter/TokenMeter/UsageViewModel.swift

@@ -41,6 +41,14 @@ struct DashboardView: View {
                                 apiUtilization: summary.rateLimits.apiWeekly
                             )
 
+                            Divider()
+                                .padding(.vertical, 4)
+
+                            // Usage Heatmap
+                            if !summary.hourly.isEmpty {
+                                UsageHeatmapView(hourly: summary.hourly)
+                            }
+
                             Divider()
                                 .padding(.vertical, 4)