ccusage-widget

CCUsage Widget for macOS

A beautiful macOS desktop widget that displays your Claude Code usage statistics in real-time.

📦 NPM Package

https://www.npmjs.com/package/ccusage-widget

Features

• 📊 Real-time Usage Display: Shows today's, this month's, and total usage
• 💰 Cost Tracking: Displays costs in USD for each time period
• 🤖 Model Tracking: See which Claude models you're using
• 📱 Recent Sessions: View your 5 most recent conversation sessions
• 🎨 Beautiful UI: Modern, translucent design that fits perfectly on macOS
• 🔄 Auto-refresh: Updates every minute automatically
• 📍 Flexible Positioning: Place the widget in any corner of your screen
• 👻 Adjustable Opacity: Control the widget's transparency
• 📏 Resizable Height: Drag the bottom edge to adjust widget height
• 🚀 System Tray Integration: Easy access from the menu bar

Prerequisites

• ccusage CLI tool: This widget requires the ccusage CLI tool to be installed and working.

  Install ccusage globally:

  npm install -g ccusage
  

  Or use it with npx:

  npx ccusage
  

• Claude Code data: The widget reads usage data from ~/.claude/projects/. Make sure you have used Claude Code and have data files in this directory.

Installation

📦 NPM Package: https://www.npmjs.com/package/ccusage-widget

Option 1: Install from npm (Recommended)

npx ccusage-widget

Or install globally:

npm install -g ccusage-widget
ccusage-widget

Option 2: Build from source

• Clone this repository:

git clone https://github.com/JeongJaeSoon/ccusage-widget.git
cd ccusage-widget

• Install dependencies:

npm install

• Build the application:

npm run build

• Run the widget:

npm start

Development

To run in development mode with hot reload:

npm run dev

Building for Distribution

To create a distributable macOS app:

npm run dist

The built app will be in the release folder.

Usage

• Show/Hide: Click the system tray icon or use the context menu
• Position: Right-click the tray icon and select Position to move the widget
• Opacity: Use the slider at the bottom of the widget to adjust transparency
• Refresh: Click the refresh button or wait for auto-refresh every minute
• Minimize: Click the minimize button to hide the widget

Requirements

• macOS 10.14 or later
• Node.js 16 or later
• ccusage CLI tool (see Prerequisites above)
• Claude Code usage data (the widget reads from ~/.claude/projects/)

Technologies Used

• Electron
• TypeScript
• ccusage npm package
• Native macOS vibrancy effects

License

MIT