CCBuddy - Building a Native macOS Menu Bar App to Monitor Claude Code Usage

As a heavy Claude Code user, I always wondered how many tokens I was consuming and how much it was costing me. So I built CCBuddy - a native macOS menu bar app to solve this problem.

The Problem

Claude Code is an incredibly powerful AI coding assistant from Anthropic. Whether you're on a Pro/Max subscription or using the API with pay-as-you-go pricing, understanding your usage is crucial.

The challenge? Claude Code doesn't provide a visual usage dashboard. All your conversation logs are quietly stored in JSONL files under ~/.claude/projects/, but analyzing them requires manual effort.

I decided to build a native macOS application that makes token usage and costs crystal clear.

What is CCBuddy?

CCBuddy is a lightweight macOS menu bar application that:

• Real-time monitoring of Claude Code token usage and costs
• Dual mode support: Pro/Max subscription (5-hour rolling window) and API pay-as-you-go mode
• Cost projection: Estimates total cost based on current "burn rate"
• Historical analysis: View usage trends by day/week/month with charts
• Completely offline: All calculations happen locally, zero network requests

It sits quietly in your menu bar, ready to show you the stats whenever you need them.

Key Features

Dual Mode Pricing

Pro/Max Mode - For subscription users:

• 5-hour rolling time window
• Real-time usage percentage and remaining time
• Burn rate and cost projection

API Mode - For pay-as-you-go users:

• Today/This Week/This Month/All-time cumulative costs
• No time window constraints

Comprehensive Cost Calculation

Supports pricing for all Claude models, including the latest Claude Opus 4.5:

Notably, CCBuddy fully supports Prompt Caching cost calculation - a detail many tools overlook. Claude's caching mechanism generates additional cache_creation_input_tokens and cache_read_input_tokens, which have different pricing than regular tokens.

Glassmorphism UI

As a native macOS app, I wanted it to blend seamlessly with the system. Using SwiftUI + AppKit's NSVisualEffectView, I achieved the signature macOS glassmorphism effect:

• Adjustable opacity
• Multiple material styles (Ultra Thin to Ultra Thick)
• Smooth animations and transitions

Technical Deep Dive

Architecture

The project follows MVVM architecture with approximately 3,000 lines of Swift code:

CCBuddy/
├── Models/           # Data models
├── Services/         # Business logic (parsing, calculation, file watching)
├── ViewModels/       # UI state management
├── Views/            # SwiftUI views
└── Utilities/        # Helpers and extensions

Real-time Monitoring Pipeline

This is the heart of the application. How do we efficiently monitor file changes and update the UI?

FileWatcher (0.5s polling)
    ↓
Change detected, mark as dirty
    ↓
Timer check (default 10s)
    ↓
Quick modification time check (avoid unnecessary parsing)
    ↓
JSONLParser parses session data
    ↓
UsageCalculator computes statistics
    ↓
UsageViewModel publishes updates
    ↓
SwiftUI automatically refreshes UI

Key optimizations:

• Dirty flag marking: Only re-parse when files actually change
• Modification time check: Quickly skip unchanged files
• Deduplication: Based on requestId + messageId to avoid double-counting

JSONL Parsing

Claude Code stores data in JSONL format (one JSON object per line):

{
  "type": "assistant",
  "sessionId": "xxx-xxx-xxx",
  "timestamp": "2025-12-02T13:03:29.591Z",
  "message": {
    "model": "claude-opus-4-5-20251101",
    "usage": {
      "input_tokens": 9,
      "cache_creation_input_tokens": 5095,
      "cache_read_input_tokens": 12610,
      "output_tokens": 5
    }
  }
}

Parsing considerations:

• Only process messages with type: "assistant" (user messages aren't billed)
• Correctly accumulate all four token types
• Handle multi-session, multi-project data aggregation

Swift Charts Visualization

Using the Swift Charts framework for usage history visualization:

Chart(dailyData) { item in
    BarMark(
        x: .value("Date", item.date),
        y: .value("Cost", item.cost)
    )
    .foregroundStyle(.blue.gradient)
}

Supports day/week/month view switching for intuitive trend analysis.

Development Insights

Menu Bar App Gotchas

macOS menu bar apps (LSUIElement) have some quirks:

• No Dock icon
• No main window
• Manual management of Popover show/hide states

The NSStatusItem + NSPopover combination is the best practice.

Bridging SwiftUI and AppKit

Pure SwiftUI can't achieve certain effects (like true glassmorphism), requiring NSViewRepresentable to bridge AppKit:

struct VisualEffectView: NSViewRepresentable {
    func makeNSView(context: Context) -> NSVisualEffectView {
        let view = NSVisualEffectView()
        view.material = .hudWindow
        view.blendingMode = .behindWindow
        return view
    }
}

Automated Release Pipeline

I configured a complete GitHub Actions workflow:

• Automatic release build compilation
• Package into .app bundle with proper Info.plist
• Create DMG installer with custom icon using create-dmg
• Auto-publish GitHub Release with changelog

This makes version releases effortless.

User Experience

After installation, CCBuddy lives in your menu bar. Click the icon to see:

┌────────────────────────────────────┐
│ ▊▊▊  CCBuddy   Pro          10s   │
├────────────────────────────────────┤
│ Session Progress              35% │
│ ████████████░░░░░░░░░░░░░░░░░░░░  │
│                                   │
│ 📄 Tokens Used             7.4M   │
│ 💲 Session Cost         $3.1725   │
│ 🕐 Time Remaining         3:58    │
│ 📈 Projected Cost       $22.10    │
│ 🔥 Burn Rate         186.2K/min   │
└────────────────────────────────────┘

At a glance, you can see:

• Token consumption in the current period
• Current spending
• Remaining time in the window
• Projected cost at current rate

No more worrying about unknowingly overspending!

Tech Stack

• Language: Swift 5.9+
• UI Framework: SwiftUI + AppKit
• Charts: Swift Charts
• Minimum OS: macOS 14.0 (Sonoma)
• Build System: Swift Package Manager
• CI/CD: GitHub Actions

Roadmap

• Usage threshold alerts (50%/75%/90%)
• Launch at login
• Historical data export
• Keyboard shortcuts
• Sparkle auto-update integration

Conclusion

CCBuddy was born from a real need. As a heavy Claude Code user, I needed a tool to track my usage, so I built one.

The entire project is approximately 3,000 lines of Swift code, follows MVVM architecture, and is completely open source. If you're also a Claude Code user, give it a try!

This blog post was written with the assistance of Claude Code, while CCBuddy quietly monitored the token consumption from my menu bar.