ccusage

Appearance

Weekly Usage ​

Weekly usage aggregates usage by week, providing a mid-range view between daily and monthly usage. ccusage weekly covers all detected sources that support weekly aggregation; ccusage claude weekly and ccusage opencode weekly focus the same view on one source.

Basic Usage ​

Show all weekly usage:

bash
ccusage weekly
ccusage claude weekly
ccusage opencode weekly

Example Output ​

text
┌────────────────┬──────────────────────┬────────┬─────────┬─────────────┬────────────┬──────────────┬────────────┐
│ Week           │ Models               │ Input  │ Output  │ Cache Create│ Cache Read │ Total Tokens │ Cost (USD) │
├────────────────┼──────────────────────┼────────┼─────────┼─────────────┼────────────┼──────────────┼────────────┤
│ 2026-05-11     │ • opus-4-1           │  1,234 │ 156,789 │       2,048 │      4,096 │      164,167 │     $87.56 │
│                │ • sonnet-4-5         │        │         │             │            │              │            │
├────────────────┼──────────────────────┼────────┼─────────┼─────────────┼────────────┼──────────────┼────────────┤
│ 2026-05-04     │ • sonnet-4-5         │  2,456 │ 234,567 │       3,072 │      6,144 │      246,239 │    $104.33 │
├────────────────┼──────────────────────┼────────┼─────────┼─────────────┼────────────┼──────────────┼────────────┤
│ 2026-04-27     │ • opus-4-1           │  3,789 │ 345,678 │       4,096 │      8,192 │      361,755 │    $156.78 │
│                │ • sonnet-4-5         │        │         │             │            │              │            │
└────────────────┴──────────────────────┴────────┴─────────┴─────────────┴────────────┴──────────────┴────────────┘

Understanding the Columns ​

The columns are identical to daily reports but aggregated by week:

  • Week: Start date of the week (configurable)
  • Agent: Source CLI, shown in unified all-source reports
  • Models: All models used during the week
  • Input/Output: Total tokens for the week
  • Cache Create/Read: Cache token usage
  • Total Tokens: Sum of all token types
  • Cost (USD): Estimated cost for the week

Command Options ​

Week Start Day ​

Configure which day starts the week:

bash
# Start week on Sunday (default)
ccusage weekly --start-of-week sunday

# Start week on Monday
ccusage weekly --start-of-week monday
ccusage weekly -w monday

# Other options: tuesday, wednesday, thursday, friday, saturday

Date Filtering ​

Filter by date range:

bash
# Show specific period
ccusage weekly --since 20260501 --until 20260531

# Show last 4 weeks
ccusage weekly --since 20260420

Sort Order ​

Control the order of weeks:

bash
# Newest weeks first (default)
ccusage weekly --order desc

# Oldest weeks first
ccusage weekly --order asc

Model Breakdown ​

See per-model weekly costs:

bash
ccusage weekly --breakdown
text
┌────────────────┬──────────────────────┬────────┬─────────┬────────────┐
│ Week           │ Models               │ Input  │ Output  │ Cost (USD) │
├────────────────┼──────────────────────┼────────┼─────────┼────────────┤
│ 2026-05-11     │ opus-4-1, sonnet-4-5 │  1,234 │ 156,789 │     $87.56 │
├────────────────┼──────────────────────┼────────┼─────────┼────────────┤
│   └─ opus-4-1  │                      │    800 │  80,000 │     $54.80 │
├────────────────┼──────────────────────┼────────┼─────────┼────────────┤
│   └─ sonnet-4-5│                      │    434 │  76,789 │     $32.76 │
└────────────────┴──────────────────────┴────────┴─────────┴────────────┘

JSON Output ​

Export weekly data as JSON:

bash
ccusage weekly --json
json
{
	"weekly": [
		{
			"week": "2026-05-11",
			"inputTokens": 1234,
			"outputTokens": 156789,
			"cacheCreationTokens": 2048,
			"cacheReadTokens": 4096,
			"totalTokens": 164167,
			"totalCost": 87.56,
			"modelsUsed": ["claude-opus-4-1-20250805", "claude-sonnet-4-5-20250929"],
			"modelBreakdowns": {
				"claude-opus-4-1-20250805": {
					"inputTokens": 800,
					"outputTokens": 80000,
					"totalCost": 54.8
				},
				"claude-sonnet-4-5-20250929": {
					"inputTokens": 434,
					"outputTokens": 76789,
					"totalCost": 32.76
				}
			}
		}
	],
	"totals": {
		"inputTokens": 7479,
		"outputTokens": 737034,
		"cacheCreationTokens": 9216,
		"cacheReadTokens": 18432,
		"totalTokens": 772161,
		"totalCost": 348.67
	}
}

Project Analysis ​

Group weekly usage by project:

bash
# Show weekly usage per project
ccusage weekly --instances

# Filter to specific project
ccusage weekly --project my-project

Cost Calculation Modes ​

Control cost calculation:

bash
# Auto mode (default)
ccusage weekly --mode auto

# Always calculate from tokens
ccusage weekly --mode calculate

# Only use pre-calculated costs
ccusage weekly --mode display

Offline Mode ​

Use cached pricing data:

bash
ccusage weekly --offline

Common Use Cases ​

bash
# See usage trends over past months
ccusage weekly --since 20260401

Sprint Analysis ​

bash
# Track usage during 2-week sprints (Monday start)
ccusage weekly --start-of-week monday --since 20260501

Budget Planning ​

bash
# Export for weekly budget tracking
ccusage weekly --json > weekly-budget.json

Compare Workweeks ​

bash
# Monday-Friday work pattern analysis
ccusage weekly --start-of-week monday --breakdown

Team Reporting ​

bash
# Weekly team usage report
ccusage weekly --instances --start-of-week monday

Tips ​

  1. Week Start: Choose a start day that aligns with your work schedule
  2. Breakdown View: Use --breakdown to identify which models drive costs
  3. JSON Export: Weekly JSON data is perfect for creating trend charts
  4. Project Tracking: Use --instances to track project-specific weekly usage

Released under the MIT License.

Copyright © 2025 ryoppippi