ccusage supports JSON configuration files for persistent settings. Configuration files allow you to set default options for all commands or customize behavior for specific commands without repeating options every time.
Always include the schema for autocomplete and validation:
{
"$schema": "https://ccusage.com/config-schema.json"
}Put frequently used options in defaults:
{
"$schema": "https://ccusage.com/config-schema.json",
"defaults": {
"timezone": "UTC",
"breakdown": true
}
}{
"$schema": "https://ccusage.com/config-schema.json",
"defaults": {
"breakdown": false
},
"commands": {
"daily": {
"breakdown": true // Only daily needs breakdown
}
}
}If you find yourself repeating CLI arguments:
# Before (repeated CLI arguments)
ccusage daily --breakdown --instances --timezone UTC
ccusage monthly --breakdown --timezone UTCConvert them to a config file:
// ccusage.json
{
"$schema": "https://ccusage.com/config-schema.json",
"defaults": {
"breakdown": true,
"timezone": "UTC"
},
"commands": {
"daily": {
"instances": true
}
}
}Now simpler commands:
ccusage daily
ccusage monthlyccusage searches for configuration files in these locations (in priority order):
- Local project:
.ccusage/ccusage.json(higher priority) - User config:
~/.claude/ccusage.jsonor~/.config/claude/ccusage.json(lower priority)
Configuration files are merged in priority order, with local project settings overriding user settings.
If you pass a custom config file using --config, it will override both local and user configs.
Note that configuration files are not required; if none are found, ccusage will use built-in defaults.
Also, if you have multiple config files, only the first one found will be used.
Create a ccusage.json file with your preferred defaults:
{
"$schema": "https://ccusage.com/config-schema.json",
"defaults": {
"json": false,
"mode": "auto",
"offline": false,
"noCost": false,
"timezone": "Asia/Tokyo",
"breakdown": true
}
}Add the $schema property to get IntelliSense and validation in your IDE:
{
"$schema": "https://ccusage.com/config-schema.json"
}You can also reference a local schema file after installing ccusage:
{
"$schema": "./node_modules/ccusage/config-schema.json"
}The defaults section sets shared default values for unified reports and legacy Claude commands:
{
"$schema": "https://ccusage.com/config-schema.json",
"defaults": {
"since": "20260101",
"until": "20260531",
"json": false,
"mode": "auto",
"debug": false,
"debugSamples": 5,
"order": "asc",
"breakdown": false,
"offline": false,
"noCost": false,
"timezone": "UTC"
}
}Set noCost to true to hide cost columns in tables and remove cost fields from JSON output by default.
Override shared defaults for specific unified reports and legacy Claude commands using the commands section:
{
"$schema": "https://ccusage.com/config-schema.json",
"defaults": {
"mode": "auto",
"offline": false
},
"commands": {
"daily": {
"instances": true,
"breakdown": true
},
"blocks": {
"active": true,
"tokenLimit": "500000"
}
}
}Use data source namespaces to set defaults and report overrides. Supported namespaces are claude, codex, opencode, amp, droid, codebuff, hermes, pi, goose, openclaw, kilo, kimi, qwen, copilot, gemini, antigravity, grok, and zcode.
{
"$schema": "https://ccusage.com/config-schema.json",
"defaults": {
"json": false,
"timezone": "UTC"
},
"codex": {
"defaults": {
"json": true,
"offline": true
},
"commands": {
"daily": {
"since": "20260101",
"until": "20260131"
}
}
},
"opencode": {
"commands": {
"weekly": {
"timezone": "Europe/London"
}
}
},
"droid": {
"defaults": {
"offline": true
}
},
"codebuff": {
"commands": {
"daily": {
"json": true
}
}
},
"pi": {
"stores": [
{
"name": "omp",
"path": "~/.omp/agent/sessions"
}
],
"defaults": {
"piPath": "/path/to/pi/sessions,/archive/pi/sessions"
}
},
"openclaw": {
"defaults": {
"openClawPath": "/path/to/openclaw,/archive/openclaw"
}
},
"kilo": {
"defaults": {
"offline": true
}
},
"kimi": {
"defaults": {
"offline": true
}
},
"qwen": {
"defaults": {
"offline": true
}
},
"copilot": {
"defaults": {
"offline": true
}
},
"gemini": {
"defaults": {
"offline": true
}
},
"zcode": {
"defaults": {
"offline": true
}
}
}This configuration affects source-focused commands such as:
ccusage codex daily
ccusage opencode weekly
ccusage droid daily
ccusage codebuff daily
ccusage pi daily
ccusage openclaw daily
ccusage kilo daily
ccusage kimi daily
ccusage qwen daily
ccusage copilot monthly
ccusage gemini daily
ccusage antigravity daily
ccusage zcode dailySource-specific settings are also applied when running unified reports such as ccusage daily. In that case, each source receives its own merged options before data is loaded.
Use pi.stores for additional pi-format session stores, such as tools or forks that write sessions outside ~/.pi/agent/sessions. Named stores are additive to the default pi agent in unified reports, use their own agent name in JSON and tables, and prefix models with [name] followed by a space. Store names must match ^[a-z][a-z0-9_-]{0,31}$, must be unique, and cannot use a built-in agent name. Each store path can be one sessions directory or a comma-separated list; ~ is expanded for store paths, nonexistent paths are treated as empty, and resolved paths that overlap the default pi store or another named store — including one path nested inside another — are rejected. They do not create focused commands such as ccusage omp daily; PI_AGENT_DIR, --pi-path, and pi.defaults.piPath still affect only the default pi agent.
For a namespaced command, options are applied in this order:
defaultscommands.<report><source>.defaults<source>.commands.<report>- Command-line arguments
{
"commands": {
"daily": {
"instances": true,
"project": "my-project",
"breakdown": true,
"since": "20260101",
"until": "20260531"
}
}
}{
"commands": {
"weekly": {
"startOfWeek": "monday",
"breakdown": true,
"timezone": "Europe/London"
}
}
}{
"commands": {
"monthly": {
"breakdown": true,
"mode": "calculate"
}
}
}{
"commands": {
"session": {
"id": "abc123-session",
"project": "my-project",
"json": true
}
}
}{
"commands": {
"blocks": {
"active": true,
"recent": false,
"tokenLimit": "max",
"sessionLength": 5,
"live": false,
"refreshInterval": 1
}
}
}{
"commands": {
"statusline": {
"offline": true,
"cache": true,
"refreshInterval": 2,
"modelLabelAliases": {
"arn:aws:bedrock:ap-northeast-1:012345678910:application-inference-profile/abcde12345": "claude-opus-4-6"
}
}
}
}Use the --config option to specify a custom configuration file:
# Use a specific configuration file
ccusage daily --config ./my-config.json
# Works with all commands
ccusage blocks --config /path/to/team-config.jsonccusage looks up token costs from a LiteLLM pricing snapshot embedded in the binary, optionally refreshed at runtime (or skipped with --offline). When a model is missing from LiteLLM (private deployments, internal wrappers like Pi's [pi] gpt-5.4, custom proxies), or when the snapshot price differs from your contract, set pricingOverrides under defaults to supply per-model values.
{
"$schema": "https://ccusage.com/config-schema.json",
"defaults": {
"pricingOverrides": {
"[pi] gpt-5.4": {
"inputCostPerToken": 0.0000025,
"outputCostPerToken": 0.000015,
"cacheReadInputTokenCost": 0.00000025
},
"my-private-claude": {
"inputCostPerToken": 0.000003,
"outputCostPerToken": 0.000015,
"maxInputTokens": 1000000
}
}
}
}Keys in pricingOverrides must match the raw model name as recorded in the source logs, including any adapter prefix:
| Adapter | Prefix | Example key |
|---|---|---|
| Pi | [pi] |
[pi] gpt-5.4 |
| Named Pi store | [name] |
[omp] gpt-5.4 |
| Others (Claude, Codex, OpenCode, etc.) | none | claude-sonnet-4-5, gpt-5.5 |
To find the exact name, run ccusage <agent> daily --json and look at the model field in the per-row breakdown.
All fields are optional. Unspecified fields fall back to the LiteLLM entry (when one exists) or 0.0:
inputCostPerToken,outputCostPerToken— base per-token ratescacheCreationInputTokenCost,cacheReadInputTokenCost— cache pricinginputCostPerTokenAbove200kTokens,outputCostPerTokenAbove200kTokens,cacheCreationInputTokenCostAbove200kTokens,cacheReadInputTokenCostAbove200kTokens— tiered pricing past 200k tokensmaxInputTokens— context window limit (used by the Claude statusline hook)fastMultiplier— multiplier applied when the message is recorded as fast-mode
--offline and pricingOverrides are independent:
--offlinecontrols the data source — skip the network refresh and use the embedded LiteLLM snapshot only.pricingOverridescontrols specific entries — patch in or replace prices for individual models.
Overrides apply in both online and offline modes.
This is useful for:
- Team configurations - Share configuration files across team members
- Environment-specific settings - Different configs for development/production
- Project-specific overrides - Use different settings for different projects
For a complete configuration example, see /ccusage.example.json in the repository root, which demonstrates:
- Global defaults configuration
- Command-specific overrides
- All available options with proper types
Settings are applied in this priority order (highest to lowest):
- Command-line arguments (e.g.,
--json,--offline) - Custom config file (specified with
--config /path/to/config.json) - Local project config (
.ccusage/ccusage.json) - User config (
~/.config/claude/ccusage.json) - Legacy config (
~/.claude/ccusage.json) - Built-in defaults
Example:
// .ccusage/ccusage.json
{
"defaults": {
"mode": "calculate"
}
}# Config file sets mode to "calculate"
ccusage daily # Uses mode: calculate
# But CLI argument overrides it
ccusage daily --mode display # Uses mode: displayUse the --debug flag to see configuration loading details:
# Debug configuration loading
ccusage daily --debug
# Debug custom config file
ccusage daily --debug --config ./my-config.jsonDebug output shows:
- Which config files are checked and found
- Schema and option details from loaded configs
- How options are merged from different sources
- Final values used for each option
Example debug output:
[ccusage] ℹ Debug mode enabled - showing config loading details
[ccusage] ℹ Searching for config files:
• Checking: .ccusage/ccusage.json (found ✓)
• Checking: ~/.config/claude/ccusage.json (found ✓)
• Checking: ~/.claude/ccusage.json (not found)
[ccusage] ℹ Loaded config from: .ccusage/ccusage.json
• Schema: https://ccusage.com/config-schema.json
• Has defaults: yes (3 options)
• Has command configs: yes (daily)
[ccusage] ℹ Merging options for 'daily' command:
• From defaults: mode="auto", offline=false
• From command config: instances=true
• From CLI args: debug=true
• Final merged options: {
mode: "auto" (from defaults),
offline: false (from defaults),
instances: true (from command config),
debug: true (from CLI)
}
For project configs, commit .ccusage/ccusage.json to version control:
# Add to git
git add .ccusage/ccusage.json
git commit -m "Add ccusage configuration"Add comments using a README alongside team configs:
team-configs/
├── ccusage.json
└── README.md # Explain configuration choices
- Check file location is correct
- Verify JSON syntax is valid
- Use
--debugto see loading details - Ensure option names match exactly
Use a JSON validator or IDE with JSON support:
# Validate JSON syntax
jq . < ccusage.jsonEnsure option values match expected types:
{
"defaults": {
"tokenLimit": "500000", // ✅ String or number
"active": true, // ✅ Boolean
"refreshInterval": 2 // ✅ Number
}
}- Command-Line Options - Available CLI arguments
- Environment Variables - Environment configuration
- Configuration Overview - Complete configuration guide