session

Claude usage grouped by sessionId. Resumed sessions (same sessionId across multiple JSONL files via claude --resume) collapse into a single row. 11-column layout that parallels codex-session.

Cost coverage: Claude dollar and token totals are transcript-derived lower bounds, not exact /usage billing totals.

Canonical form: cctally claude session (this flat form remains as an alias).

Synopsis

cctally session
    [-s YYYYMMDD] [-u YYYYMMDD]
    [-b] [-o {asc,desc}]
    [-m {auto,calculate,display}]
    [--json]

Options

Flag	Description
-s, --since YYYYMMDD	Filter from date (inclusive).
-u, --until YYYYMMDD	Filter until date (inclusive).
-b, --breakdown	Show per-model cost breakdown sub-rows.
-o, --order {asc,desc}	Sort direction by last activity (default asc — earliest first).
-m, --mode {auto,calculate,display}	Cost source (drop-in for ccusage session --mode). auto (default) uses the recorded costUSD from JSONL when present, else computes from embedded pricing. calculate always computes from embedded pricing, ignoring any recorded costUSD. display shows the recorded costUSD only, rendering $0.00 when a session has none (ccusage-faithful). Most modern Claude Code JSONL omits costUSD, so under display near-everything reports $0.
--tz TZ	Display timezone for this call (local, utc, or IANA, e.g. America/New_York). Overrides config display.tz. See Display timezone for the full contract (parsing scope, JSON UTC invariant).
--json	Output JSON.

Behavior note (auto, sessions with legacy costUSD). Before the --mode work, session was the one report that always recomputed cost from embedded pricing and ignored any recorded costUSD — even though daily, monthly, weekly, and the dashboard already preferred the recorded value. The default auto mode now aligns session (and the TUI session views, which have no --mode flag) with those reports: for sessions whose JSONL carries costUSD, default totals reflect the recorded cost rather than a recomputed one. Only the ~3.9% of historical files that still carry costUSD are affected; everything else is unchanged. Pass --mode calculate to force the old always-recompute behavior.

Examples

cctally session
cctally session --since 20260401
cctally session --since 20260401 --breakdown
cctally session --json
cctally session --order desc

How resume merging works

Each JSONL file under ~/.claude/projects/ is associated with a sessionId extracted from the first line carrying it. The session_files.session_id column in cache.db stores that mapping. This command groups session_entries by sessionId (joined on source_path), so all entries from a --resume-extended session collapse into one row.

The Directory column shows the most-recent project if the resume crossed cwds. The JSON output's sourcePaths array preserves the full list of files.

Token totals

Total Tokens (the table column, the per-model --breakdown sub-rows, and the JSON totalTokens field — both per-session and the totals roll-up) sums all four token components: input + output + cacheCreation + cacheRead. This matches daily / monthly and upstream ccusage v20 (issue #104). The JSON field name and shape are unchanged — only the value widened to include cache, so a consumer that previously read totalTokens as input+output will now see the cache-inclusive figure.

codex-session reports the same "all tokens processed" semantic, but its surface formula stays input + output because Codex inputTokens is already cache-inclusive (LiteLLM convention) — adding cache there would double-count.

Gotchas

• session_files is populated lazily. On the first command run after a deploy, some entries may briefly lack session_id / project_path. The aggregator falls back to the filename UUID as sessionId and emits a one-shot stderr warning: Warning: N entries lacked session_files rows (cache may be catching up). Subsequent runs backfill the metadata via sync_cache().
• Sort defaults to ascending (earliest first) to match codex-session's "scrollback-friendly" default.

See also

• codex-session — Codex equivalent (same column layout)
• Architecture · cache.db

Shareable output

cctally session accepts --format {md,html,svg} and related flags for shareable artifacts. See share.md for the full flag reference.