| name | ccost |
| description | Use when Codex needs to inspect, summarize, compare, or troubleshoot local Claude Code, Codex, or OpenCode usage costs with the ccost CLI. Covers daily/monthly token and cost reports, JSON or table output, per-model breakdowns, project grouping, agent filtering, date ranges, timezone grouping, and offline pricing behavior. |
ccost
Overview
Use ccost to report local Claude Code, Codex, and OpenCode token usage and costs. Prefer the installed ccost binary on PATH; when working inside the ccost repository and no binary is installed, use cargo run -- <args>.
Do not read or print raw session JSONL, local config, tokens, cookies, authorization headers, or other secret-bearing files unless the user explicitly asks for the raw source and the output has been reviewed for secrets.
Quick Start
Run the smallest command that answers the user's question:
ccost daily
ccost monthly
ccost daily --json
ccost daily --kmb
ccost monthly --json
ccost monthly --kmb
If the user omits a period, start with daily. Use JSON when the user asks for data to process, precise totals, or a machine-readable answer; use table output for human-readable summaries.
Common Tasks
Summarize recent usage:
ccost daily --since 20260101 --until 20260131
ccost monthly --since 20260101 --until 20261231
Filter by agent source:
ccost daily --agent codex
ccost daily --agent claudecode
ccost monthly --agent codex,opencode
Show model-level details:
ccost daily --breakdown
ccost monthly --breakdown --json
Group daily output by project or filter one project:
ccost daily --instances
ccost daily --project my-project
Control ordering and timezone grouping:
ccost daily --order desc
ccost daily --timezone UTC
ccost monthly --timezone America/New_York
Data Locations
Let ccost discover default locations first. Override only when the user gives a non-default location or asks to diagnose missing data.
- Claude Code:
$XDG_CONFIG_HOME/claude, ~/.config/claude, then ~/.claude; override with comma-separated CLAUDE_CONFIG_DIR.
- Codex:
${CODEX_HOME:-~/.codex}/sessions.
- OpenCode:
${OPENCODE_DATA_DIR:-~/.local/share/opencode}/opencode.db, with legacy fallback under storage/message.
Pricing
By default, ccost uses bundled offline pricing snapshots. Use live pricing only when the user asks for it or when investigating pricing drift:
ccost daily --offline=false
ccost monthly --offline=false --json
Cost modes:
--mode auto: use recorded costUSD when present, otherwise calculate from tokens.--mode calculate: always calculate from token counts.--mode display: always use recorded costUSD.
Interpreting Results
When reporting back to the user, lead with the total cost, token count, date range, agent filter, and pricing mode used. Mention if no usage data was found and include the exact command that produced the result.
If ccost is unavailable:
- Check whether
ccost exists on PATH.
- If inside the repository, use
cargo run -- <ccost-args>.
- Otherwise, tell the user to install it with Homebrew or Cargo rather than recreating ccost logic manually.
