CCUsage Mac Widget

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

---

✨ Features

• 📊 Interactive Line Chart - Visualize your daily Claude Code usage over time
• 💰 Cost Tracking - Prominent display of total spending with detailed breakdowns
• 🎨 Beautiful Design - Modern, translucent UI with blur effects and smooth animations
• 🔄 Auto-Refresh - Automatically updates every 30 seconds
• 🪟 Always On Top - Stays visible while you work, draggable to any position
• 📈 Daily Insights - See trends in your token usage and costs

📸 Screenshot

🚀 Quick Start

Prerequisites

Before you begin, ensure you have:

• Node.js (v16 or higher) - Download here
• npm (v7 or higher) - Comes with Node.js
• ccusage CLI - The Claude Code usage tracking tool installed and available in your PATH

To verify ccusage is installed:

which ccusage
ccusage --version

If you don't have ccusage installed, please install it first from the ccusage repository.

Installation

1. Clone the repository

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

2. Install dependencies

   npm install

3. Run the widget

   npm start

The widget will launch as a floating window on your desktop!

🎯 Usage

Basic Operation

• Start the widget: Run npm start from the project directory
• Move the widget: Click and drag anywhere on the widget
• Close the widget: Click the red close button in the top-right corner
• Resize: The widget is resizable - drag from the edges

Understanding the Display

The widget shows:

• Total Cost - Your cumulative spending displayed prominently at the top
• Line Chart - Daily cost breakdown over time with interactive hover tooltips
• Date Range - The time period covered by your usage data

Auto-Refresh

The widget automatically fetches new data every 30 seconds to keep your statistics up to date.

⚙️ Configuration

Customize Refresh Interval

Edit renderer.js and modify the interval (in milliseconds):

// Default: 30 seconds
setInterval(updateUsage, 30000);

// Change to 60 seconds
setInterval(updateUsage, 60000);

Adjust Window Size

Edit main.js and modify the window dimensions:

mainWindow = new BrowserWindow({
  width: 500,  // Change width
  height: 450, // Change height
  // ...
});

Customize Appearance

The widget's appearance can be customized by editing the CSS in index.html:

• Colors: Search for color values (e.g., #30d158 for green)
• Transparency: Adjust rgba() values and backdrop-filter
• Chart styling: Modify Chart.js options in renderer.js

🏗️ Project Structure

ccusage-mac-widget/
├── main.js           # Electron main process
├── preload.js        # Secure IPC bridge
├── index.html        # UI layout and styling
├── renderer.js       # Chart rendering and data fetching
├── package.json      # Project metadata and dependencies
├── README.md         # This file
├── LICENSE           # MIT license
└── .gitignore        # Git ignore rules

🛠️ Development

Debug Mode

To open Chrome DevTools for debugging, uncomment this line in main.js:

mainWindow.webContents.openDevTools();

Tech Stack

• Electron - Desktop application framework
• Chart.js - Interactive chart library
• Node.js - JavaScript runtime
• ccusage - Claude Code usage data source

🐛 Troubleshooting

Widget shows "Invalid data format" error

1. Verify ccusage is working:

   ccusage --json

2. Ensure you have usage data:

   ccusage daily

3. Check that ccusage returns valid JSON

Widget won't start

1. Check Node.js version:

   node --version  # Should be >= 16.0.0

2. Reinstall dependencies:

   rm -rf node_modules package-lock.json
   npm install

3. Look for error messages in the terminal

Close button doesn't work

Try using Cmd+Q to quit the application, then restart with npm start.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Electron
• Charts powered by Chart.js
• Data from ccusage
• Inspired by the need for better Claude Code usage visibility