Skip to content

Configuration Overview ​

ccusage provides multiple ways to configure its behavior, allowing you to customize it for your specific needs. Report options come from command-line options and configuration files; environment variables tell ccusage where each source stores its data.

Configuration Methods ​

ccusage supports three configuration methods, each with its own use case:

  1. Command-Line Options - Direct control for individual commands
  2. Configuration Files - Persistent, shareable settings
  3. Environment Variables - Data source directories and log level

Configuration Priority ​

Report options are applied in this priority order (highest to lowest):

  1. Command-line arguments (e.g., --json, --offline)
  2. The configuration file - the --config file when given, otherwise the first of .ccusage/ccusage.json and the user config files that exists and holds a JSON object; see Configuration Files
  3. Built-in defaults

No environment variable sets a report option such as the timezone or the cost mode.

Priority Example ​

In .ccusage/ccusage.json:

json
{
	"defaults": {
		"mode": "calculate"
	}
}
bash
# The configuration file sets mode to "calculate"
ccusage daily

# A command-line argument takes priority
ccusage daily --mode display

Quick Start ​

Basic Setup ​

  1. Set custom data directories (only if not using defaults):
bash
export CODEX_HOME="$HOME/.codex"
export GEMINI_DATA_DIR="$HOME/.gemini/tmp"
export OPENCODE_DATA_DIR="$HOME/.local/share/opencode"
export AMP_DATA_DIR="$HOME/.local/share/amp"
export CLINE_DATA_DIR="$HOME/.cline,/path/to/globalStorage/saoudrizwan.claude-dev"
export PI_AGENT_DIR="$HOME/.pi/agent/sessions"
export KILO_DATA_DIR="$HOME/.local/share/kilo"
export COPILOT_HOME="$HOME/.copilot"
export COPILOT_OTEL_FILE_EXPORTER_PATH="$COPILOT_HOME/otel/copilot-otel.jsonl"
export ZCODE_HOME="$HOME/.zcode"
export DSH_HOME="$HOME/.dsh"

Use comma-separated directories when you want reports to combine multiple profiles or archives:

bash
export CODEX_HOME="$HOME/.codex,$HOME/.codex-work"
export GEMINI_DATA_DIR="$HOME/.gemini/tmp,/backup/gemini/tmp"
export OPENCODE_DATA_DIR="$HOME/.local/share/opencode,/archive/opencode"
export CLINE_DATA_DIR="$HOME/.cline,/archive/cline"
export KILO_DATA_DIR="$HOME/.local/share/kilo,/backup/kilo"
  1. Create a configuration file for your preferences:
json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"timezone": "America/New_York",
		"breakdown": true
	}
}
  1. Use command-line options for one-off changes:
bash
ccusage daily --since 20260101 --json

Common Configuration Scenarios ​

Personal Development ​

For individual developers working on multiple projects, in ~/.config/claude/ccusage.json:

json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"breakdown": true,
		"timezone": "local"
	},
	"claude": {
		"commands": {
			"daily": {
				"instances": true
			}
		}
	}
}

instances groups ccusage claude daily by project; the unified ccusage daily has no project grouping.

Multiple Sources ​

Configure Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Cline, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Antigravity, Grok Build CLI, ZCode, and DeepSeek Harness separately with data source namespaces in ~/.config/claude/ccusage.json:

json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"timezone": "UTC"
	},
	"claude": {
		"commands": {
			"daily": {
				"instances": true
			}
		}
	},
	"codex": {
		"defaults": {
			"json": true,
			"offline": true
		},
		"commands": {
			"daily": {
				"since": "20260101",
				"until": "20260131"
			}
		}
	},
	"cline": {
		"commands": {
			"daily": {
				"timezone": "UTC"
			}
		}
	}
}

Source sections apply to focused commands such as ccusage codex daily and ccusage amp session. They are also used by unified reports such as ccusage daily, where each source receives its own merged options before data is loaded.

Team Collaboration ​

For teams sharing configuration, commit .ccusage/ccusage.json to the repository:

json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"timezone": "UTC",
		"mode": "auto"
	}
}

CI/CD Pipeline ​

For automated environments:

bash
# Environment variables
export CODEX_HOME="/ci/codex-data"
export LOG_LEVEL=0  # Hide warnings, progress, and table titles

# Run with specific options
ccusage daily --offline --json > report.json

Configuration by Feature ​

Cost Calculation ​

Control how costs are calculated:

  • Mode: auto (default), calculate, or display
  • Offline: Use embedded pricing data
  • Breakdown: Show per-model costs
bash
ccusage daily --mode calculate --breakdown --offline

Date and Time ​

Customize date/time handling:

  • Timezone: Any valid timezone (e.g., UTC, America/New_York)
  • Date Range: Filter with --since and --until
bash
ccusage daily --timezone UTC --since 20260101

Output Format ​

Control output presentation:

  • JSON: Machine-readable output with --json
  • Debug: Show detailed information with --debug
bash
ccusage daily --json | jq ".daily[] | select(.totalCost > 10)"

Project Analysis ​

Analyze Claude Code usage by project with ccusage claude daily:

  • Instances: Group by project with --instances
  • Project Filter: Focus on specific project with --project
  • Aliases: Set custom names via configuration file

In .ccusage/ccusage.json:

json
{
	"commands": {
		"daily": {
			"projectAliases": "uuid-123=My App,long-name=Backend"
		}
	}
}
bash
ccusage claude daily --instances --project uuid-123

--project matches the project directory name; aliases only change the label shown in the table.

Debugging Configuration ​

bash
# Show skipped input and loader details on stderr
ccusage daily --debug

# Check environment variables
env | grep -E "CLAUDE|CODEX|LOG_LEVEL"

# Also log pricing refresh details
LOG_LEVEL=4 ccusage daily

Configuration diagnostics name the selected file and JSON path. In a discovered file, invalid optional fields warn while valid settings remain effective; ccusage does not fall through to another file. Invalid dates are errors for reports that use them. Statusline commands warn about invalid discovered date bounds and drop the affected bounds. Invalid named Pi stores, unreadable files and invalid JSON may also produce errors. An explicit --config file is strict. Unknown keys warn, and LOG_LEVEL=0 suppresses warnings. Check the search order when a different file shadows the one you edited.

Best Practices ​

1. Layer Your Configuration ​

Use different configuration methods for different scopes:

  • Environment variables: Machine-specific settings (paths)
  • User config or project config: Preferences and team standards (timezone, mode, formatting); ccusage reads only one of them, so a project config replaces the user config rather than extending it
  • CLI arguments: One-off overrides

2. Use Configuration Files for Teams ​

Share consistent settings across team members:

bash
# Commit to version control
git add .ccusage/ccusage.json
git commit -m "Add team ccusage configuration"

3. Document Your Configuration ​

Use a README to explain configuration choices; the JSON file itself cannot contain comments:

markdown
# ccusage Configuration

Our team uses:

- UTC timezone for consistency
- JSON output for automated processing
- Calculate mode for accurate cost tracking

4. Validate Configuration ​

Use the schema for validation:

json
{
	"$schema": "https://ccusage.com/config-schema.json"
}

5. Keep Secrets Secure ​

Never put sensitive information in configuration files:

  • ❌ API keys or tokens
  • ❌ Personal identifiers
  • ✅ Timezone preferences
  • ✅ Output formats

Migration Guide ​

From Manual Commands ​

Convert repeated commands to configuration. Before:

bash
ccusage claude daily --breakdown --instances --timezone UTC

After, with this configuration file:

json
{
	"defaults": {
		"breakdown": true,
		"timezone": "UTC"
	},
	"commands": {
		"daily": {
			"instances": true
		}
	}
}
bash
ccusage claude daily

Troubleshooting ​

Common Issues ​

  1. Configuration not applied: Check which file ccusage reads; it uses only the first valid one
  2. Invalid JSON: Validate syntax with jq; a file that does not parse is skipped without an error, and comments are not allowed
  3. Directory not found: Verify the data source environment variable
  4. No data: Check directory permissions

Getting Help ​

If configuration issues persist:

  1. Run with debug mode: ccusage daily --debug
  2. Log pricing refresh details: LOG_LEVEL=4 ccusage daily
  3. Validate JSON config: jq . < ccusage.json
  4. Report issues on GitHub

Next Steps ​

Explore specific configuration topics:

Released under the MIT License.