v18.2.0

ccusage v18.2.0 - Automated Background Sync

✨ Major New Feature: Automated Background Synchronization

Never manually run blocks-monitor again! This release introduces automated background sync that keeps your usage data synchronized across all machines without any manual intervention.

🚀 New Features

sync Command

• One-shot sync: New ccusage sync command submits current token usage and exits
• Perfect for automation: Designed for cron jobs and system services
• Silent operation: --quiet flag suppresses all output for background usage
• Replaces manual monitoring: No need to keep terminals open with blocks-monitor

System Service Files

Ready-to-use service configurations for automatic synchronization every 5 minutes:

Linux (systemd):

• ccusage-sync.service - Service unit that runs the sync command
• ccusage-sync.timer - Timer unit for 5-minute intervals
• Security hardened with read-only filesystem access

macOS (launchd):

• com.ccusage.sync.plist - LaunchAgent for background sync
• Starts automatically on login
• Logs to /tmp/ccusage-sync.log

Installation Helpers

• install-macos-service.sh - Automated installer for macOS
• test-macos-service.sh - Service verification tool
• Comprehensive documentation in system-services/README.md

🐛 Bug Fixes

• Fixed live monitor burn rate calculation to exclude cache tokens (merged from upstream)
• Burn rate indicators now only consider input/output tokens for accurate HIGH/MODERATE/NORMAL thresholds

📦 Installation

Download the appropriate binary for your platform:

• Linux x64: ccusage-linux-x64.tar.gz
• macOS x64 (Intel): ccusage-macos-x64.tar.gz
• macOS ARM64 (Apple Silicon): ccusage-macos-arm64.tar.gz

🔄 Quick Setup for Background Sync

macOS:

tar -xzf ccusage-macos-arm64.tar.gz
./install-macos-service.sh

Linux:

tar -xzf ccusage-linux-x64.tar.gz
sudo cp ccusage-linux-x64 /usr/local/bin/ccusage
sudo cp system-services/ccusage-sync.* /etc/systemd/user/
systemctl --user enable --now ccusage-sync.timer

📊 How It Works

1. The sync command reads your current Claude usage data
2. Submits it to the ccusage server (soothaa.pythonanywhere.com)
3. Exits immediately - perfect for scheduled tasks
4. Runs every 5 minutes via system services
5. Your usage data stays synchronized across all machines automatically

🔧 Manual Usage

You can still run sync manually:

ccusage sync               # Submit usage and show summary
ccusage sync --quiet       # Submit silently (for scripts)

📝 Full Changelog

• Added sync command for one-shot token submission
• Created systemd service + timer for Linux
• Created launchd plist for macOS
• Added installation and test scripts
• Updated dependencies from upstream
• Fixed burn rate calculation in live monitor
• Enhanced documentation with service setup instructions

🙏 Credits

Thanks to @ryoppippi for the original ccusage project and the upstream fixes!