{"id":29942789,"url":"https://github.com/evanlong-me/claude-code-usage","last_synced_at":"2025-10-13T13:42:18.300Z","repository":{"id":306803100,"uuid":"1027244857","full_name":"evanlong-me/claude-code-usage","owner":"evanlong-me","description":"📊 A command-line tool to analyze and summarize your code usage with Claude AI.","archived":false,"fork":false,"pushed_at":"2025-07-30T13:27:11.000Z","size":11956,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-01T23:58:10.190Z","etag":null,"topics":["ai","anthropic","claude","claude-code","cli","statistics","usage","wrapper"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/claude-code-usage","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evanlong-me.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-27T16:10:46.000Z","updated_at":"2025-07-30T13:27:13.000Z","dependencies_parsed_at":"2025-07-27T19:10:37.997Z","dependency_job_id":null,"html_url":"https://github.com/evanlong-me/claude-code-usage","commit_stats":null,"previous_names":["evanlong-me/claude-code-usage"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/evanlong-me/claude-code-usage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanlong-me%2Fclaude-code-usage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanlong-me%2Fclaude-code-usage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanlong-me%2Fclaude-code-usage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanlong-me%2Fclaude-code-usage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evanlong-me","download_url":"https://codeload.github.com/evanlong-me/claude-code-usage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanlong-me%2Fclaude-code-usage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279015350,"owners_count":26085684,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","anthropic","claude","claude-code","cli","statistics","usage","wrapper"],"created_at":"2025-08-03T02:03:19.123Z","updated_at":"2025-10-13T13:42:18.294Z","avatar_url":"https://github.com/evanlong-me.png","language":"JavaScript","readme":"# Claude Code Usage\n\nA lightweight CLI tool for analyzing Claude Code usage statistics and costs locally.\n\n## ✨ Features\n\n- 🔒 **100% Local \u0026 Secure** - No API keys required, reads local Claude Code data only\n- ⚡ **Quick Analysis** - View all usage statistics with a single `ccu` command\n- 💰 **Cost Tracking** - Accurate cost calculation based on Claude pricing\n- 📊 **Dual View Modes** - Switch between daily aggregated view and detailed message view\n- 🎯 **Smart Project Detection** - Auto-detects current project when run in project directories\n- 📋 **Clean Table Display** - Organized tabular output with token counts, costs, and project info\n- 🔍 **Smart Filtering** - Filter by time ranges and project names\n- 📈 **Flexible Sorting** - Sort by cost, time, tokens, or project name\n- 🔄 **Auto Update Check** - Automatically checks for new versions and notifies when updates are available\n- 🚀 **Easy to Use** - Simple installation and intuitive commands\n\n## 🚀 Quick Start\n\n### Global Installation (Recommended)\n```bash\nnpm install -g claude-code-usage\nccu  # View statistics instantly\n```\n\n### Alternative Installation Methods\n\n```bash\n# One-time usage (no installation required)\nnpx claude-code-usage\n\n# Local project installation\nnpm install claude-code-usage\nnpx claude-code-usage\n```\n\n## 📋 Usage\n\n### Basic Commands\n\nThese are the basic commands you can use:\n\n```bash\n# View usage statistics (default command)\nccu\n\n# Display version information\nccu -v\n\n# Display help information\nccu --help\n\n# List all available projects\nccu --list-projects\n# or use the short form\nccu -lp\n\n# List all available models with pricing\nccu --list-models\n# or use the short form\nccu -lm\n```\n\n### 🔍 Filtering Options\n\nFilter your usage data by time range and project. \n\n**Note**: It's recommended to wrap time filters in quotes if they contain spaces.\n\n#### ⏰ Time Filtering Formats\n\nThe tool supports various time filtering formats for maximum flexibility:\n\n**Relative Time Filters** (no quotes needed):\n- `5min`, `30min` - Last N minutes\n- `2h`, `12h` - Last N hours  \n- `7d`, `30d` - Last N days\n- `1m`, `6m` - Last N months\n- `1y`, `2y` - Last N years\n\n**Date Range Filters**:\n- `6-8` - Month range (June to August, current year)\n- `july-august`, `jan-mar` - Named month ranges\n- `2024-7-2024-8` - Cross-year month ranges\n- `2024-07-01,2024-08-31` - Specific date ranges\n\n**Precise DateTime Filters** (ISO 8601 format, **recommended**):\n- `2024-07-30T16:00:00,2024-07-30T18:00:00` - Second precision\n- `2024-07-30T16:00,2024-07-30T18:00` - Minute precision\n- `2024-07-30T16,2024-07-30T18` - Hour precision\n\n**Human-readable DateTime** (requires quotes):\n- `\"2024-07-30 16:00:00,2024-07-30 18:00:00\"` - Second precision\n- `\"2024-07-30 16:00,2024-07-30 18:00\"` - Minute precision\n\n```bash\n# Filter by relative time (no quotes needed)\nccu -t 5min         # Last 5 minutes\nccu -t 2h           # Last 2 hours\nccu -t 7d           # Last 7 days\nccu -t 1m           # Last 1 month\nccu -t 1y           # Last 1 year\n\n# Filter by month range (no quotes needed)\nccu -t 6-8          # June to August (current year)\nccu -t july-august  # July to August (current year)\n\n# Filter by date and time (T-separator, no quotes needed)\nccu -t 2024-07-01T14:30:15,2024-07-01T16:45:30  # With seconds\nccu -t 2024-07-01T14:30,2024-07-01T16:45     # With minutes\nccu -t 2024-07-01T14,2024-07-01T16         # With hours\n\n# Filter by date and time (space separator, quotes needed)\nccu -t \"2024-07-01 14:30,2024-07-01 16:45\"\n\n# Filter by specific date range\nccu -t 2024-07-01,2024-08-31\nccu -t 2024-7-2024-8      # July 2024 to August 2024\n\n# Filter by project (partial matching supported)\nccu -p myproject    # Show only messages from projects containing \"myproject\"\n\n# Combine filters for precise results\nccu -t 1m -p my-website # Last month's my-website project data\n```\n\n### 📈 Sorting Options\n\nSort your results by different criteria:\n\n```bash\n# Sort by cost (highest first)\nccu -s cost -o desc\n\n# Sort by cost (lowest first)\nccu -s cost -o asc\n\n# Sort by total tokens\nccu -s tokens -o desc\n\n# Sort by project name\nccu -s project -o asc\n\n# Sort by time (default)\nccu -s time -o desc\n\n# Combine sorting with filtering\nccu -p my-website -s cost -o desc  # my-website project sorted by cost\n```\n\n### 🎯 Project Auto-Detection\n\nThe tool automatically detects your current project and filters results accordingly:\n\n```bash\n# When run in a project directory, automatically filters to that project\ncd my-project\nccu                     # Shows only my-project usage\n\n# Show all projects explicitly\nccu --all               # Shows usage for all projects\nccu -a\n\n# Manual project filtering still works\nccu -p specific-project # Shows only specific-project usage\n```\n\n### 📊 View Modes\n\nSwitch between different viewing modes:\n\n```bash\n# Default: aggregated view (by project and date)\nccu\n\n# Detailed view: show individual messages\nccu --detailed\nccu -d\n\n# Comparing views for specific projects\nccu -p my-project       # Aggregated entry for my-project\nccu -p my-project -d    # All individual my-project messages\n```\n\n### ⭐ GitHub Prompt Configuration\n\nManage the GitHub star prompt that appears after displaying results:\n\n```bash\n# Permanently disable the GitHub star prompt\nccu --disable-github-prompt\n\n# Re-enable the GitHub star prompt\nccu --enable-github-prompt\n\n# View all available options (including prompt settings)\nccu -h\n```\n\nThe tool will show a friendly prompt asking you to star the repository on GitHub after displaying usage statistics. You can:\n\n- **Keep it enabled** (default) - Helps support the project\n- **Disable it permanently** - The setting is saved and respected across all future runs\n- **Re-enable it anytime** - If you change your mind\n\nYour preference is stored in `~/.claude-code-usage-config.json`.\n\n### 🅰️ All Options Reference\n\nComplete reference table of all available options:\n\n| Option | Description | Values | Default |\n|--------|-------------|--------|---------|\n| `-t, --time` | Time filter | `5min`, `2h`, `7d`, `1m`, `1y`, `6-8`, `july-august`, `2024-07-01T14:30,2024-07-01T16:45`, etc. | - |\n| `-p, --project` | Project filter | Project name (partial matching) | auto-detect |\n| `-s, --sort` | Sort field | `cost`, `time`, `tokens`, `project` | `time` |\n| `-o, --order` | Sort order | `asc`, `desc` | `desc` |\n| `-d, --detailed` | Show individual messages | - | `false` (aggregated) |\n| `-a, --all` | Show all projects | - | `false` (auto-detect) |\n| `-lp, --list-projects` | List all projects | - | - |\n| `-lm, --list-models` | List all available models with pricing | - | - |\n| `--disable-github-prompt` | Permanently disable the GitHub star prompt | - | - |\n| `--enable-github-prompt` | Re-enable the GitHub star prompt | - | - |\n\n## 📊 Sample Output\n\nAn example of what the output may look like:\n\n```\n🔍 Options applied:\n  Project: my-website\n  Sort: cost ↓\n  Results: 3 aggregated entries (45 messages from 58 total)\n\n┌─────────────┬─────────────┬──────────┬───────┬────────┬──────────────┬────────────┬──────────────────────────┬───────────┬───────────┐\n│ Time        │ Project     │ Messages │ Input │ Output │ Cache Create │ Cache Read │ Model                    │ Total     │ Cost      │\n├─────────────┼─────────────┼──────────┼───────┼────────┼──────────────┼────────────┼──────────────────────────┼───────────┼───────────┤\n│ 6/29/2025   │ my-website  │ 15       │ 1,200 │ 400    │ 60,000       │ 20,000     │ claude-sonnet-4-20250514 │ 81,600    │ $0.249000 │\n├─────────────┼─────────────┼──────────┼───────┼────────┼──────────────┼────────────┼──────────────────────────┼───────────┼───────────┤\n│ 6/28/2025   │ my-website  │ 20       │ 800   │ 300    │ 40,000       │ 15,000     │ claude-sonnet-4-20250514 │ 56,100    │ $0.168500 │\n├─────────────┼─────────────┼──────────┼───────┼────────┼──────────────┼────────────┼──────────────────────────┼───────────┼───────────┤\n│ 6/27/2025   │ my-website  │ 10       │ 845   │ 428    │ 198,600      │ 652,976    │ claude-sonnet-4-20250514 │ 852,849   │ $0.734798 │\n├─────────────┼─────────────┼──────────┼───────┼────────┼──────────────┼────────────┼──────────────────────────┼───────────┼───────────┤\n│ TOTAL       │             │ 45       │ 2,845 │ 1,128  │ 298,600      │ 687,976    │                          │ 990,549   │ $1.152298 │\n└─────────────┴─────────────┴──────────┴───────┴────────┴──────────────┴────────────┴──────────────────────────┴───────────┴───────────┘\n```\n\n### 📁 Project List Output\n\n```bash\nccu --list-projects\n# or use short form: ccu -lp\n```\n\n```\n📁 Available projects:\n  • my-website (45 messages)\n  • data-analysis (8 messages)\n  • chatbot-app (5 messages)\n```\n\n## 🛠️ Requirements\n\n- **Node.js** \u003e= 14.0.0\n- **Claude Code** installed and configured\n- At least one Claude Code project with conversation history\n\n## 📁 Data Sources\n\nThis tool reads Claude Code usage data from your local files:\n\n- `~/.claude.json` - Main Claude Code configuration\n- `~/.claude/projects/` - Session records and project data\n- `~/.claude/settings.json` - User settings (optional)\n\n## 🚨 Setup Instructions\n\nFirst time using this tool? If Claude Code isn't configured on your system, you'll see:\n\n```\n❌ Claude Code configuration not found!\n\n📋 To fix this:\n\n1. Install Claude Code:\n   npm install -g @anthropic-ai/claude-code\n\n2. Authenticate:\n   claude\n   # Follow authentication prompts\n\n3. Start a conversation:\n   claude \"Hello, world!\"\n\n4. Run this tool:\n   ccu\n```\n\n## 🔒 Privacy \u0026 Security\n\n- **100% Local Data** - All Claude Code usage data read from your local files\n- **Minimal Network Usage** - Only fetches model pricing from LiteLLM (cached for 1 hour)\n- **No API Keys** - No authentication required\n- **Privacy First** - Your usage data never leaves your machine\n\n## 🤝 Contributing\n\nContributions welcome! Please submit a Pull Request.\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🐛 Issues\n\nFound a bug? [Create an issue](https://github.com/evanlong-me/claude-code-usage/issues)\n\n## 📚 Links\n\n- [NPM Package](https://www.npmjs.com/package/claude-code-usage)\n- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code/settings)\n","funding_links":[],"categories":["HarmonyOS"],"sub_categories":["Windows Manager"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevanlong-me%2Fclaude-code-usage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevanlong-me%2Fclaude-code-usage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevanlong-me%2Fclaude-code-usage/lists"}