From b8332d96a227c291f2754bee8ec2395ed9b97d40 Mon Sep 17 00:00:00 2001 From: Martin Wilke Date: Mon, 30 Jun 2025 21:19:14 +0800 Subject: [PATCH 1/2] BUMP: Version 1.0.4 - ready for next development cycle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit πŸ€– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index fe89064..388443d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "cost-tracker", - "version": "1.0.3", + "version": "1.0.4", "description": "Complete Claude API Cost Monitoring Tool - React/Electron", "main": "dist/main.js", "scripts": { From 5d19f5cc181f2eb57619542e9e06dc047af9227c Mon Sep 17 00:00:00 2001 From: Martin Wilke Date: Mon, 30 Jun 2025 21:24:05 +0800 Subject: [PATCH 2/2] IMPROVE: Restructure README.md for better organization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove significant duplication and redundant content - Reduce from 340 to 159 lines (50% reduction) - Improve structure with logical flow - Make sections more concise and scannable - Maintain all essential information - Better user experience for new contributors πŸ€– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.md | 347 +++++++++++++----------------------------------------- 1 file changed, 83 insertions(+), 264 deletions(-) diff --git a/README.md b/README.md index 1cc13da..3f4b1be 100644 --- a/README.md +++ b/README.md @@ -1,339 +1,158 @@ -# CCTracker - Claude Code Tracker +# CCTracker - Claude Code CLI Usage Monitor
![CCTracker Dashboard](img/gh_img.png) -**Professional Claude Code CLI usage monitoring and cost analytics** -*CCTracker = Claude Code Tracker* +**Professional Claude Code CLI usage monitoring and cost analytics** [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![React](https://img.shields.io/badge/React-20232A?logo=react&logoColor=61DAFB)](https://reactjs.org/) [![Electron](https://img.shields.io/badge/Electron-191970?logo=Electron&logoColor=white)](https://www.electronjs.org/) -[Features](#features) β€’ [Installation](#installation) β€’ [Usage](#usage) β€’ [Screenshots](#screenshots) β€’ [Technical Architecture](#technical-architecture) β€’ [Contributing](#contributing) +[Features](#features) β€’ [Installation](#installation) β€’ [Usage](#usage) β€’ [Development](#development) β€’ [Contributing](#contributing)
## Overview -CCTracker (Claude Code Tracker) is a comprehensive desktop application specifically designed for monitoring **Claude Code CLI** usage and costs. Built with React and Electron, it provides real-time tracking, advanced analytics, and detailed insights into your Claude Code command-line tool consumption patterns. +CCTracker monitors **Claude Code CLI** usage and costs in real-time. Built with React and Electron, it provides comprehensive analytics for developers using the Claude Code command-line tool. -> **Important**: This tool monitors the **Claude Code CLI** (claude.ai/code) usage and costs, not the Claude.ai web interface. CCTracker tracks API usage from the command-line tool that developers use for coding assistance. - -### 🎯 Key Benefits - -- **Real-time Monitoring**: Automatically tracks Claude Code CLI usage with live file monitoring -- **Cost Analytics**: Detailed cost breakdowns with multi-currency support (USD, EUR, GBP, JPY, CNY, MYR) -- **Business Intelligence**: Advanced analytics with predictive insights and optimization recommendations -- **Multi-language Support**: Available in 6 languages (English, German, French, Spanish, Japanese, Chinese) -- **Professional UI**: Modern, accessible interface with multiple themes including dark mode and Catppuccin themes +> **Note**: This monitors the Claude Code CLI ([claude.ai/code](https://claude.ai/code)), not the Claude.ai web interface. ## Features -### πŸ“Š **Dashboard & Analytics** -- **Real-time Usage Tracking**: Monitor Claude Code CLI API calls as they happen -- **Cost Breakdown**: Detailed analysis by model, project, and time period -- **Token Analytics**: Input/output token tracking with cache optimization metrics -- **Session Management**: Track coding sessions and their efficiency -- **Project-level Analytics**: Drill down into specific project usage patterns - -### πŸ’° **Cost Management** -- **Multi-currency Support**: View costs in 6 different currencies with live exchange rates -- **Cache Savings Tracking**: Monitor cache read/write tokens and cost savings -- **Budget Predictions**: Forecast monthly costs based on usage patterns -- **Cost Optimization**: AI-powered recommendations for reducing API costs - -### πŸ“ˆ **Business Intelligence** -- **Usage Patterns**: Identify peak usage times and efficiency opportunities -- **Model Efficiency Analysis**: Compare performance and cost-effectiveness across Claude models -- **Anomaly Detection**: Automatic detection of unusual usage patterns -- **Trend Analysis**: Historical data analysis with growth projections - -### 🌍 **Internationalization** -- **6 Languages**: English, German, French, Spanish, Japanese, Chinese (Simplified) -- **Cultural Localization**: Proper date/time formatting and currency display -- **RTL Support**: Ready for right-to-left languages - -### 🎨 **User Experience** -- **Professional Themes**: Light, Dark, and 4 Catppuccin theme variants -- **Responsive Design**: Works seamlessly across different screen sizes -- **Accessibility**: WCAG 2.1 compliant with keyboard navigation and screen reader support -- **Smooth Animations**: Polished UI with smooth transitions and loading states - -### πŸ“€ **Data Export** -- **Multiple Formats**: Export data as CSV, JSON, or Excel -- **Flexible Filtering**: Export specific date ranges or projects -- **Scheduled Exports**: Set up automatic data exports (planned feature) +- **πŸ“Š Real-time Monitoring**: Live tracking of Claude Code CLI usage and costs +- **πŸ’° Multi-currency Support**: View costs in USD, EUR, GBP, JPY, CNY, MYR with live rates +- **πŸ“ˆ Advanced Analytics**: Usage patterns, model efficiency, anomaly detection +- **🌍 Internationalization**: 6 languages with proper localization +- **🎨 Professional UI**: Light/dark themes + 4 Catppuccin variants +- **πŸ“€ Data Export**: CSV, JSON, Excel export with flexible filtering +- **πŸ”’ Privacy-first**: All data stored locally, no cloud sync ## Installation -### Prerequisites - -- **Node.js**: Version 18.0 or higher -- **Claude Code CLI**: Installed and configured for API access ([claude.ai/code](https://claude.ai/code)) -- **Operating System**: macOS 10.14+ or Linux (Ubuntu 18.04+) - -### Quick Start - -1. **Clone the repository** - ```bash - git clone https://github.com/miwi-fbsd/CCTracker.git - cd CCTracker - ``` +### Download -2. **Install dependencies** - ```bash - npm install - ``` +Get the latest release from [GitHub Releases](https://github.com/miwi-fbsd/CCTracker/releases): +- **macOS**: Download `.dmg` file +- **Linux**: Download `.deb` or `.tar.gz` file -3. **Start development server** - ```bash - npm run dev - ``` +### Prerequisites -4. **Build for production** - ```bash - npm run build - npm start - ``` +- **Claude Code CLI**: Must be installed and configured ([claude.ai/code](https://claude.ai/code)) +- **Operating System**: macOS 10.14+ or Linux (Ubuntu 18.04+) -### Building Distributables +### From Source ```bash -# Build for current platform -npm run package - -# Build for specific platforms -npm run package:mac # macOS (Universal) -npm run package:linux # Linux (x64) +git clone https://github.com/miwi-fbsd/CCTracker.git +cd CCTracker +npm install +npm run build +npm start ``` -## Screenshots - -### Dashboard Overview -![CCTracker Main Dashboard](img/gh_img.png) - -The main dashboard provides real-time monitoring of your Claude Code CLI usage with: -- **Live Cost Tracking**: Real-time cost updates with multi-currency support -- **Usage Analytics**: Token consumption and session statistics -- **Visual Charts**: Daily spending analysis and model usage breakdown -- **Theme Support**: 6 professional themes including dark mode and Catppuccin variants -- **Export Capabilities**: CSV and JSON export with comprehensive data filtering - - ## Usage -### Initial Setup - -1. **Launch CCTracker**: Open the application after installation -2. **Configure Settings**: Set your preferred language, theme, and currency -3. **Start Claude Code CLI**: Use Claude Code CLI normally - CCTracker automatically detects usage -4. **Monitor Usage**: View real-time updates in the dashboard - -### Core Workflows - -#### **Dashboard Monitoring** -- View real-time cost and token usage -- Monitor active sessions and recent activity -- Track daily/weekly/monthly spending trends - -#### **Project Analytics** -- Click on any project card to view detailed analytics -- Analyze model efficiency and cache utilization -- Review cost trends and optimization opportunities - -#### **Business Intelligence** -- Access advanced analytics and predictive insights -- Generate cost forecasts and budget recommendations -- Identify usage patterns and optimization opportunities - -#### **Data Export** -- Export usage data for external analysis -- Generate reports for cost accounting -- Archive historical data for compliance +1. **Install & Launch**: Download and install CCTracker +2. **Auto-detection**: CCTracker automatically monitors `~/.claude/projects/` for Claude CLI usage +3. **Configure**: Set language, theme, and currency in Settings +4. **Monitor**: View real-time usage and costs as you use Claude Code CLI -### Configuration +### Key Workflows -CCTracker automatically detects Claude Code CLI configuration. For manual setup: +- **Dashboard**: Real-time cost tracking and usage analytics +- **Projects**: Detailed project-level analysis and trends +- **Export**: Generate CSV/JSON reports for external analysis +- **Settings**: Customize themes, language, and currency preferences -1. **Settings Panel**: Access via the gear icon in the header -2. **Data Location**: CCTracker monitors `~/.claude/projects/` by default (Claude Code CLI log files) -3. **Currency Rates**: Automatically updated with live exchange rates -4. **Themes & Language**: Customize appearance and localization - -## Technical Architecture +## Development -### Technology Stack +### Tech Stack -- **Frontend**: React 18.3.1 with TypeScript 5.8.3 -- **Desktop Framework**: Electron 37.1.0 -- **Build System**: Webpack 5.99.9 with separate main/renderer configs -- **Styling**: Tailwind CSS 3.4.17 with CSS custom properties -- **Charts**: Recharts 2.15.4 for data visualization -- **Date Picker**: react-datepicker 8.4.0 with custom theming -- **Internationalization**: react-i18next 13.5.0 with i18next 23.16.8 -- **Icons**: Heroicons 2.2.0 for UI icons -- **Testing**: Jest 29.7.0 with React Testing Library 14.3.1 -- **File Monitoring**: Chokidar 3.6.0 for real-time file watching -- **Data Export**: ExcelJS 4.4.0 for Excel file generation +- **Frontend**: React 18 + TypeScript 5.8 +- **Desktop**: Electron 37 +- **Build**: Webpack 5 + Tailwind CSS +- **Charts**: Recharts for data visualization +- **i18n**: react-i18next for 6 languages +- **File Monitoring**: Chokidar for real-time JSONL parsing -### Architecture Overview +### Architecture ``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Claude Code CLI │───▢│ File System │───▢│ CCTracker β”‚ -β”‚ (JSONL logs) β”‚ β”‚ Monitoring β”‚ β”‚ Dashboard β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β–Ό - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Cost Engine β”‚ - β”‚ & Analytics β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +Claude Code CLI β†’ File Monitor β†’ Cost Engine β†’ React Dashboard + (JSONL) (Chokidar) (Analytics) (Electron) ``` -- **File Monitoring**: Real-time JSONL file parsing from Claude Code CLI -- **Cost Calculation**: Accurate pricing with cache token optimization -- **Data Processing**: In-memory caching with persistent storage -- **IPC Communication**: Secure bridge between main and renderer processes - -### Project Structure +### Setup -``` -CCTracker/ -β”œβ”€β”€ src/ -β”‚ β”œβ”€β”€ main/ # Electron main process -β”‚ β”‚ β”œβ”€β”€ main.ts # Application entry point -β”‚ β”‚ β”œβ”€β”€ ipc/ # IPC handlers -β”‚ β”‚ β”œβ”€β”€ services/ # Core business logic -β”‚ β”‚ └── utils/ # Utilities -β”‚ β”œβ”€β”€ renderer/ # React frontend -β”‚ β”‚ β”œβ”€β”€ components/ # UI components -β”‚ β”‚ β”œβ”€β”€ contexts/ # React contexts -β”‚ β”‚ β”œβ”€β”€ hooks/ # Custom hooks -β”‚ β”‚ β”œβ”€β”€ i18n/ # Internationalization -β”‚ β”‚ └── styles/ # Global styles -β”‚ └── shared/ # Shared types & utilities -β”‚ β”œβ”€β”€ types.ts # TypeScript interfaces -β”‚ β”œβ”€β”€ constants.ts # App constants -β”‚ └── utils/ # Shared utilities -β”œβ”€β”€ webpack.*.config.js # Build configurations -β”œβ”€β”€ package.json # Dependencies & scripts -└── README.md # This file +```bash +git clone https://github.com/miwi-fbsd/CCTracker.git +cd CCTracker +npm install +npm run dev # Development with hot reload +npm run build # Production build +npm run package # Create distributable ``` -## Development +### Scripts + +- `npm run dev` - Start development server +- `npm run lint` - ESLint checking +- `npm run type-check` - TypeScript validation +- `npm test` - Jest test suite + +## Contributing -### Development Environment - -1. **Clone & Install** - ```bash - git clone - cd CCTracker - npm install - ``` - -2. **Start Development Server** - ```bash - npm run dev - ``` - This starts: - - Webpack dev server for React (port 8080) - - Main process build watcher - - Electron app with hot reload - -3. **Code Quality** - ```bash - npm run lint # ESLint checking - npm run type-check # TypeScript validation - npm test # Jest test suite - ``` - -### Contributing Guidelines - -1. **Fork the repository** and create a feature branch -2. **Follow code standards**: ESLint, TypeScript strict mode, React best practices -3. **Add tests** for new functionality -4. **Update documentation** for any API changes -5. **Submit a pull request** with clear description +1. Fork the repository and create a feature branch +2. Follow code standards: ESLint, TypeScript strict mode, React best practices +3. Add tests for new functionality +4. Submit a pull request with clear description ### Code Standards - **TypeScript**: Strict mode enabled, comprehensive type coverage -- **React**: Modern hooks-based components, Context API for state +- **React**: Modern hooks-based components with Context API - **Accessibility**: WCAG 2.1 Level AA compliance -- **Internationalization**: All user-facing text must be translatable -- **Testing**: Unit tests for business logic, integration tests for workflows - -## Security & Privacy - -### Data Handling - -- **Local Storage**: All data stored locally on your machine -- **No Cloud Sync**: No data transmitted to external servers -- **File Access**: Only reads Claude CLI logs, no modification -- **Privacy First**: Your API usage data never leaves your device - -### Security Features - -- **Sandboxed Renderer**: Electron context isolation enabled -- **IPC Validation**: All inter-process communication validated -- **No Remote Code**: No external code execution -- **Audit Trail**: All file access logged for transparency +- **i18n**: All user-facing text must be translatable ## Troubleshooting -### Common Issues - -**Q: CCTracker not detecting Claude Code CLI usage** -- Verify Claude Code CLI is installed and configured ([claude.ai/code](https://claude.ai/code)) -- Check that JSONL logging is enabled in Claude Code CLI -- Ensure CCTracker has file system permissions to read `~/.claude/projects/` +**Not detecting Claude CLI usage?** +- Verify Claude Code CLI is installed ([claude.ai/code](https://claude.ai/code)) +- Check file permissions for `~/.claude/projects/` -**Q: Cost calculations seem incorrect** -- Verify currency exchange rates are up to date -- Check if cache tokens are being calculated properly -- Review model pricing in settings +**Cost calculations incorrect?** +- Verify currency rates are updated +- Check cache token calculations -**Q: Application won't start** +**App won't start?** - Ensure Node.js 18+ is installed -- Clear `node_modules` and reinstall: `rm -rf node_modules && npm install` -- Check for port conflicts (default: 8080) +- Clear and reinstall: `rm -rf node_modules && npm install` -### Performance Optimization - -- **Large Datasets**: CCTracker handles 10K+ entries efficiently -- **Memory Usage**: Automatic cleanup prevents memory leaks -- **File Monitoring**: Optimized for minimal CPU usage -- **UI Rendering**: Virtualized lists for large data sets +## Security & Privacy +- **Local-only**: All data stored locally, no cloud sync +- **Read-only**: Only reads Claude CLI logs, never modifies +- **Sandboxed**: Electron context isolation enabled +- **Privacy-first**: Your usage data never leaves your device ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +MIT License - see [LICENSE](LICENSE) file for details. ## Support -### Getting Help - -- **Documentation**: Check this README and inline help -- **Issues**: Report bugs via GitHub Issues -- **Discussions**: Join community discussions -- **Email**: Contact maintainers for enterprise support - -### Community - -- **GitHub**: [CCTracker Repository](https://github.com/miwi-fbsd/CCTracker) +- **Issues**: [GitHub Issues](https://github.com/miwi-fbsd/CCTracker/issues) - **Discussions**: [GitHub Discussions](https://github.com/miwi-fbsd/CCTracker/discussions) -- **Issues**: [Bug Reports](https://github.com/miwi-fbsd/CCTracker/issues) ---
-**Built with ❀️ for the Claude Code CLI community** +**Built for the Claude Code CLI community** [⭐ Star this repo](https://github.com/miwi-fbsd/CCTracker) if you find it helpful!