| Name | claude-code-cost JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | Claude Code Cost Calculator - Analyze token usage and costs from Claude Code history |
| upload_time | 2025-07-26 15:18:13 |
| maintainer | None |
| docs_url | None |
| author | keakon |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Claude Code Cost Calculator
A Python tool for analyzing Claude Code usage history, calculating token consumption and costs across projects and time periods.
English | [中文](README_CN.md)
## Features
- **Multi-model Support**: Claude Sonnet, Opus, Gemini models with accurate pricing
- **Comprehensive Analytics**: Daily usage trends, project rankings, model performance, and cost breakdowns
- **Smart Display**: Automatically hides empty sections and optimizes long project paths
- **Model Insights**: Individual model consumption tracking with cost ranking (shown when using 2+ models)
- **Data Export**: JSON export for further analysis
- **Time Zone Handling**: Converts UTC timestamps to local time for accurate daily statistics
- **Internationalization**: Auto-detects system language, supports English and Chinese (Simplified/Traditional)
## Installation
### Quick Install (One-liner)
```bash
# Auto-detect best installation method for your system
curl -sSL https://raw.githubusercontent.com/keakon/claude-code-cost/main/install.sh | bash
```
### Option 1: Install from PyPI (Recommended)
#### Using uv (Recommended - Modern & Fast)
```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install as a global tool
uv tool install claude-code-cost
# Run the command
ccc
```
#### Using pipx (Traditional alternative)
```bash
# Install pipx if you don't have it
brew install pipx # macOS
# or: python -m pip install --user pipx # Linux/Windows
# Install claude-code-cost as an isolated tool
pipx install claude-code-cost
# Now you can run from anywhere
ccc
```
#### Using pip with virtual environment
```bash
# Create a dedicated virtual environment
python -m venv ~/.venvs/claude-cost
source ~/.venvs/claude-cost/bin/activate # Linux/macOS
# or: ~/.venvs/claude-cost/Scripts/activate # Windows
pip install claude-code-cost
ccc
```
### Option 2: Install from Source
```bash
# Clone the repository
git clone https://github.com/keakon/claude-code-cost.git
cd claude-code-cost
# Install in development mode
uv pip install -e .
# Or using pip
pip install -e .
```
### Requirements
- Python 3.8+
- Dependencies: `rich`, `pyyaml`
## Usage
### Basic Usage
```bash
# Analyze with default settings (after installing from PyPI)
ccc
# Or if installed from source
python main.py
# Specify custom data directory
ccc --data-dir /path/to/.claude/projects
```
### Advanced Options
```bash
# Customize display limits
ccc --max-days 7 --max-projects 5
# Show all data
ccc --max-days 0 --max-projects 0
# Display costs in Chinese Yuan (CNY)
ccc --currency CNY
# Use custom exchange rate
ccc --currency CNY --usd-to-cny 7.3
# Export to JSON
ccc --export-json report.json
# Debug mode
ccc --log-level DEBUG
# Force English interface
ccc --language en
# Force Chinese interface
ccc --language zh
```
## Output Sections
The tool displays up to 5 main sections:
1. **Overall Statistics**: Total projects, tokens, and costs
2. **Today's Usage**: Current day consumption by project (shown only when active)
3. **Daily Statistics**: Historical trends (shown only when historical data exists)
4. **Project Rankings**: Top projects by cost
5. **Model Statistics**: Individual model consumption and ranking (shown when using 2+ models)
## Configuration
The tool comes with built-in default pricing for all supported models, but you can customize pricing by creating a user configuration file.
### Custom Configuration
Create a configuration file at `~/.claude-code-cost/model_pricing.yaml` to override default settings:
```bash
# Create config directory
mkdir -p ~/.claude-code-cost
# Create your custom configuration
cat > ~/.claude-code-cost/model_pricing.yaml << 'EOF'
# Custom model pricing configuration
currency:
usd_to_cny: 7.3 # Exchange rate
display_unit: "USD" # Default display currency
pricing:
sonnet:
input_per_million: 3.0
output_per_million: 15.0
cache_read_per_million: 0.3
cache_write_per_million: 3.75
gemini-2.5-pro:
# Multi-tier pricing example
tiers:
- threshold: 200000 # ≤200K tokens
input_per_million: 1.25
output_per_million: 10.0
- # >200K tokens
input_per_million: 2.5
output_per_million: 15.0
qwen3-coder:
# CNY pricing example
currency: "CNY"
tiers:
- threshold: 32000 # ≤32K tokens
input_per_million: 4.0
output_per_million: 16.0
- threshold: 128000 # ≤128K tokens
input_per_million: 6.0
output_per_million: 24.0
- threshold: 256000 # ≤256K tokens
input_per_million: 10.0
output_per_million: 40.0
- # >256K tokens
input_per_million: 20.0
output_per_million: 200.0
EOF
```
### Built-in Models
The tool includes built-in pricing for:
- **Claude Models**: Sonnet, Opus
- **Gemini Models**: 1.5-Pro, 2.5-Pro (with tier pricing)
- **Qwen Models**: Qwen3-Coder (with CNY pricing and tier structure)
### Configuration Priority
1. **Built-in defaults**: Always available as fallback
2. **Package configuration**: Included with the package
3. **User configuration**: `~/.claude-code-cost/model_pricing.yaml` (highest priority)
## Command Line Options
| Option | Default | Description |
|--------|---------|-------------|
| `--data-dir` | `~/.claude/projects` | Claude projects directory |
| `--max-days` | `10` | Days to show in daily stats (0=all) |
| `--max-projects` | `10` | Projects to show in rankings (0=all) |
| `--currency` | `USD` | Display currency (USD/CNY) |
| `--usd-to-cny` | `7.0` | Exchange rate for CNY conversion |
| `--language` | `auto` | Interface language (en/zh), auto-detected |
| `--log-level` | `WARNING` | Logging level |
| `--export-json` | - | Export results to JSON file |
## Data Sources
The tool analyzes JSONL files in your Claude projects directory, typically located at:
- **macOS**: `~/.claude/projects`
- **Linux**: `~/.claude/projects`
- **Windows**: `%USERPROFILE%\.claude\projects`
## Contributing
Contributions welcome! Please feel free to submit issues and pull requests.
## Code Attribution
Approximately 99% of this project's code was generated by [Claude Code](https://claude.ai/code).
## License
MIT License - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "claude-code-cost",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "keakon",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9c/40/2ab86114dcab4b33a570c30078c04d34a4af8ed89ff127ee63eacd80b988/claude_code_cost-1.0.0.tar.gz",
"platform": null,
"description": "# Claude Code Cost Calculator\n\nA Python tool for analyzing Claude Code usage history, calculating token consumption and costs across projects and time periods.\n\nEnglish | [\u4e2d\u6587](README_CN.md)\n\n\n\n## Features\n\n- **Multi-model Support**: Claude Sonnet, Opus, Gemini models with accurate pricing\n- **Comprehensive Analytics**: Daily usage trends, project rankings, model performance, and cost breakdowns \n- **Smart Display**: Automatically hides empty sections and optimizes long project paths\n- **Model Insights**: Individual model consumption tracking with cost ranking (shown when using 2+ models)\n- **Data Export**: JSON export for further analysis\n- **Time Zone Handling**: Converts UTC timestamps to local time for accurate daily statistics\n- **Internationalization**: Auto-detects system language, supports English and Chinese (Simplified/Traditional)\n\n## Installation\n\n### Quick Install (One-liner)\n\n```bash\n# Auto-detect best installation method for your system\ncurl -sSL https://raw.githubusercontent.com/keakon/claude-code-cost/main/install.sh | bash\n```\n\n### Option 1: Install from PyPI (Recommended)\n\n#### Using uv (Recommended - Modern & Fast)\n```bash\n# Install uv if you don't have it\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install as a global tool\nuv tool install claude-code-cost\n\n# Run the command\nccc\n```\n\n#### Using pipx (Traditional alternative)\n```bash\n# Install pipx if you don't have it\nbrew install pipx # macOS\n# or: python -m pip install --user pipx # Linux/Windows\n\n# Install claude-code-cost as an isolated tool\npipx install claude-code-cost\n\n# Now you can run from anywhere\nccc\n```\n\n#### Using pip with virtual environment\n```bash\n# Create a dedicated virtual environment\npython -m venv ~/.venvs/claude-cost\nsource ~/.venvs/claude-cost/bin/activate # Linux/macOS\n# or: ~/.venvs/claude-cost/Scripts/activate # Windows\n\npip install claude-code-cost\nccc\n```\n\n### Option 2: Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/keakon/claude-code-cost.git\ncd claude-code-cost\n\n# Install in development mode\nuv pip install -e .\n\n# Or using pip\npip install -e .\n```\n\n### Requirements\n- Python 3.8+\n- Dependencies: `rich`, `pyyaml`\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Analyze with default settings (after installing from PyPI)\nccc\n\n# Or if installed from source\npython main.py\n\n# Specify custom data directory\nccc --data-dir /path/to/.claude/projects\n```\n\n### Advanced Options\n\n```bash\n# Customize display limits\nccc --max-days 7 --max-projects 5\n\n# Show all data\nccc --max-days 0 --max-projects 0\n\n# Display costs in Chinese Yuan (CNY)\nccc --currency CNY\n\n# Use custom exchange rate\nccc --currency CNY --usd-to-cny 7.3\n\n# Export to JSON\nccc --export-json report.json\n\n# Debug mode\nccc --log-level DEBUG\n\n# Force English interface\nccc --language en\n\n# Force Chinese interface\nccc --language zh\n```\n\n## Output Sections\n\nThe tool displays up to 5 main sections:\n\n1. **Overall Statistics**: Total projects, tokens, and costs\n2. **Today's Usage**: Current day consumption by project (shown only when active)\n3. **Daily Statistics**: Historical trends (shown only when historical data exists)\n4. **Project Rankings**: Top projects by cost\n5. **Model Statistics**: Individual model consumption and ranking (shown when using 2+ models)\n\n## Configuration\n\nThe tool comes with built-in default pricing for all supported models, but you can customize pricing by creating a user configuration file.\n\n### Custom Configuration\n\nCreate a configuration file at `~/.claude-code-cost/model_pricing.yaml` to override default settings:\n\n```bash\n# Create config directory\nmkdir -p ~/.claude-code-cost\n\n# Create your custom configuration\ncat > ~/.claude-code-cost/model_pricing.yaml << 'EOF'\n# Custom model pricing configuration\ncurrency:\n usd_to_cny: 7.3 # Exchange rate\n display_unit: \"USD\" # Default display currency\n\npricing:\n sonnet:\n input_per_million: 3.0\n output_per_million: 15.0\n cache_read_per_million: 0.3\n cache_write_per_million: 3.75\n\n gemini-2.5-pro:\n # Multi-tier pricing example\n tiers:\n - threshold: 200000 # \u2264200K tokens\n input_per_million: 1.25\n output_per_million: 10.0\n - # >200K tokens\n input_per_million: 2.5\n output_per_million: 15.0\n\n qwen3-coder:\n # CNY pricing example\n currency: \"CNY\"\n tiers:\n - threshold: 32000 # \u226432K tokens\n input_per_million: 4.0\n output_per_million: 16.0\n - threshold: 128000 # \u2264128K tokens\n input_per_million: 6.0\n output_per_million: 24.0\n - threshold: 256000 # \u2264256K tokens\n input_per_million: 10.0\n output_per_million: 40.0\n - # >256K tokens\n input_per_million: 20.0\n output_per_million: 200.0\nEOF\n```\n\n### Built-in Models\n\nThe tool includes built-in pricing for:\n- **Claude Models**: Sonnet, Opus\n- **Gemini Models**: 1.5-Pro, 2.5-Pro (with tier pricing)\n- **Qwen Models**: Qwen3-Coder (with CNY pricing and tier structure)\n\n### Configuration Priority\n\n1. **Built-in defaults**: Always available as fallback\n2. **Package configuration**: Included with the package\n3. **User configuration**: `~/.claude-code-cost/model_pricing.yaml` (highest priority)\n\n## Command Line Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--data-dir` | `~/.claude/projects` | Claude projects directory |\n| `--max-days` | `10` | Days to show in daily stats (0=all) |\n| `--max-projects` | `10` | Projects to show in rankings (0=all) |\n| `--currency` | `USD` | Display currency (USD/CNY) |\n| `--usd-to-cny` | `7.0` | Exchange rate for CNY conversion |\n| `--language` | `auto` | Interface language (en/zh), auto-detected |\n| `--log-level` | `WARNING` | Logging level |\n| `--export-json` | - | Export results to JSON file |\n\n## Data Sources\n\nThe tool analyzes JSONL files in your Claude projects directory, typically located at:\n- **macOS**: `~/.claude/projects`\n- **Linux**: `~/.claude/projects` \n- **Windows**: `%USERPROFILE%\\.claude\\projects`\n\n## Contributing\n\nContributions welcome! Please feel free to submit issues and pull requests.\n\n## Code Attribution\n\nApproximately 99% of this project's code was generated by [Claude Code](https://claude.ai/code).\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details. ",
"bugtrack_url": null,
"license": null,
"summary": "Claude Code Cost Calculator - Analyze token usage and costs from Claude Code history",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/keakon/claude-code-cost",
"Issues": "https://github.com/keakon/claude-code-cost/issues",
"Repository": "https://github.com/keakon/claude-code-cost"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8bb1b5727e186a6e193a6ddced02edb3da7973b90b6712fec90af47d97d67fce",
"md5": "ee33c5c42fb479c72cff8c5f4f14cea4",
"sha256": "b341421ea5004f1bfd672a2f3ddf99be743beb287ee0d62f581fed826894d67d"
},
"downloads": -1,
"filename": "claude_code_cost-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ee33c5c42fb479c72cff8c5f4f14cea4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 21405,
"upload_time": "2025-07-26T15:18:09",
"upload_time_iso_8601": "2025-07-26T15:18:09.538110Z",
"url": "https://files.pythonhosted.org/packages/8b/b1/b5727e186a6e193a6ddced02edb3da7973b90b6712fec90af47d97d67fce/claude_code_cost-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9c402ab86114dcab4b33a570c30078c04d34a4af8ed89ff127ee63eacd80b988",
"md5": "1c16d3e5235dbad82a7a5305b5da2e77",
"sha256": "c1b0769972a7872f60a6359ba4915cd47d76d5bb3d4d8ac1776c00b501b62e5c"
},
"downloads": -1,
"filename": "claude_code_cost-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "1c16d3e5235dbad82a7a5305b5da2e77",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1153934,
"upload_time": "2025-07-26T15:18:13",
"upload_time_iso_8601": "2025-07-26T15:18:13.029925Z",
"url": "https://files.pythonhosted.org/packages/9c/40/2ab86114dcab4b33a570c30078c04d34a4af8ed89ff127ee63eacd80b988/claude_code_cost-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 15:18:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "keakon",
"github_project": "claude-code-cost",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "claude-code-cost"
}
