cctally 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-05-26
+
+### Added
+- **`-m/--mode {auto,calculate,display}` cost-source selector on `cctally daily`, `monthly`, `weekly`, `session`, and `blocks`** — a drop-in for `ccusage <cmd> --mode`. `auto` (the default) uses the recorded `costUSD` from JSONL when present and otherwise computes from embedded pricing; `calculate` always computes from pricing, ignoring any recorded `costUSD`; `display` shows the recorded `costUSD` only and renders `$0.00` when an entry has none (ccusage-faithful — and because most modern Claude Code JSONL omits `costUSD`, `display` reports `$0` for nearly everything). On `blocks` the mode is honored on both the main grouping and the active canonical-swapped block. `cctally five-hour-blocks` also accepts `--mode` but as a documented no-op, since its cost is the authoritative per-block value materialized at record-time. The default-`auto` output is byte-identical to before for `daily`, `monthly`, `weekly`, and `blocks`, and no `mode` key is added to any JSON shape (see the Changed note below for the one `session` exception). (#86)
+
+### Changed
+- **`cctally session` (and the TUI session views) now prefer a session's recorded `costUSD` over a recomputed cost by default, for the historical sessions whose JSONL still carries it.** `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 — so on `costUSD`-bearing windows `cctally session` totals silently disagreed with `cctally daily`. Wiring the new `--mode auto` default through the session aggregator closes that gap: default totals now match the other reports (and the shipped reconcile invariant `Σ session.totalCost == Σ daily.totalCost`). Only the ~3.9% of historical files that still carry `costUSD` are affected (modern Claude Code omits it); everything else is unchanged. The TUI session panel/detail follow the same default and have no `--mode` flag; pass `cctally session --mode calculate` on the CLI to force the previous always-recompute behavior. (#86)
+
 ## [1.15.0] - 2026-05-26
 
 ### Added

package/bin/_lib_aggregators.py

@@ -608,6 +608,7 @@ def _aggregate_codex_sessions(entries: list[CodexEntry]) -> list[CodexSessionUsa
 
 def _aggregate_claude_sessions(
     entries: list["_JoinedClaudeEntry"],
+    mode: str = "auto",
 ) -> list[ClaudeSessionUsage]:
     """Group entries by session_id, collapsing resumed-across-files sessions.
 
@@ -666,7 +667,7 @@ def _aggregate_claude_sessions(
             "cache_creation_input_tokens": entry.cache_creation_tokens,
             "cache_read_input_tokens": entry.cache_read_tokens,
         }
-        cost = _calculate_entry_cost(entry.model, usage)
+        cost = _calculate_entry_cost(entry.model, usage, mode=mode, cost_usd=entry.cost_usd)
 
         sess["input"] += entry.input_tokens
         sess["cache_create"] += entry.cache_creation_tokens

package/bin/_lib_view_models.py

@@ -318,7 +318,7 @@ class DailyView:
     display_tz_label: str = ""
 
 
-def build_daily_view(entries, *, now_utc, display_tz=None):
+def build_daily_view(entries, *, now_utc, display_tz=None, mode="auto"):
     """Build a ``DailyView`` from raw ``UsageEntry`` list (spec §5.1).
 
     Gap-free: only days with entries appear in ``view.rows`` /
@@ -336,7 +336,7 @@ def build_daily_view(entries, *, now_utc, display_tz=None):
     share consumers ignore them and read ``view.aggregated`` instead.
     """
     _agg = _load_lib("_lib_aggregators")
-    buckets = _agg._aggregate_daily(entries, mode="auto", tz=display_tz)
+    buckets = _agg._aggregate_daily(entries, mode=mode, tz=display_tz)
     if not buckets:
         return DailyView(
             rows=(),
@@ -427,7 +427,7 @@ class MonthlyView:
     display_tz_label: str = ""
 
 
-def build_monthly_view(entries, *, now_utc, n=12, display_tz=None):
+def build_monthly_view(entries, *, now_utc, n=12, display_tz=None, mode="auto"):
     """Build a ``MonthlyView`` for the trailing ``n`` calendar months
     (spec §5.2).
 
@@ -440,7 +440,7 @@ def build_monthly_view(entries, *, now_utc, n=12, display_tz=None):
     CLI table footer would.
     """
     _agg = _load_lib("_lib_aggregators")
-    buckets = _agg._aggregate_monthly(entries, mode="auto", tz=display_tz)
+    buckets = _agg._aggregate_monthly(entries, mode=mode, tz=display_tz)
     if not buckets:
         return MonthlyView(
             rows=(), aggregated=(),
@@ -528,7 +528,7 @@ class WeeklyView:
 
 
 def build_weekly_view(conn, entries, *, weeks, now_utc, display_tz=None,
-                      as_of_utc=None):
+                      as_of_utc=None, mode="auto"):
     """Build a ``WeeklyView`` from subscription-week boundaries
     (spec §5.3).
 
@@ -548,7 +548,7 @@ def build_weekly_view(conn, entries, *, weeks, now_utc, display_tz=None,
     """
     _agg = _load_lib("_lib_aggregators")
     _cct_core = _load_lib("_cctally_core")
-    buckets_asc = _agg._aggregate_weekly(entries, weeks)
+    buckets_asc = _agg._aggregate_weekly(entries, weeks, mode=mode)
     if not buckets_asc:
         return WeeklyView(
             rows=(), aggregated=(), overlay=(),
@@ -1022,7 +1022,7 @@ class SessionsView:
     display_tz_label: str = ""
 
 
-def build_sessions_view(entries, *, now_utc, limit=None, display_tz=None):
+def build_sessions_view(entries, *, now_utc, limit=None, display_tz=None, mode="auto"):
     """Build a ``SessionsView`` from joined Claude session entries
     (spec §5.5).
 
@@ -1053,7 +1053,7 @@ def build_sessions_view(entries, *, now_utc, limit=None, display_tz=None):
     """
     import os as _os                # late: keep top-level imports lean.
     _agg = _load_lib("_lib_aggregators")
-    aggregated = _agg._aggregate_claude_sessions(entries)
+    aggregated = _agg._aggregate_claude_sessions(entries, mode=mode)
     # Apply limit truncation up front so `rows` and `aggregated` stay
     # in lockstep (spec §4.3 invariant: `total_sessions == len(rows)
     # == len(aggregated)`). limit=None → keep everything.

package/bin/cctally

@@ -4238,7 +4238,7 @@ def cmd_blocks(args: argparse.Namespace) -> int:
         range_start=range_start,
         range_end=range_end,
         display_tz=tz,
-        mode="auto",
+        mode=args.mode,
         skip_rows=True,
     )
     blocks = list(view.aggregated)
@@ -4263,7 +4263,7 @@ def cmd_blocks(args: argparse.Namespace) -> int:
     # additional entries. Without re-aggregation the displayed window
     # said one thing and the cost said another (live data: window
     # 20:50→01:50 with $45 cost vs the real $128).
-    _maybe_swap_active_block_to_canonical(blocks, all_entries, now=now_utc)
+    _maybe_swap_active_block_to_canonical(blocks, all_entries, now=now_utc, mode=args.mode)
 
     if args.json:
         print(_blocks_to_json(blocks))
@@ -4284,6 +4284,7 @@ def _maybe_swap_active_block_to_canonical(
     all_entries: list[Any],
     *,
     now: dt.datetime,
+    mode: str = "auto",
 ) -> None:
     """In-place swap of an ACTIVE heuristic block to its API-anchored
     canonical window — timestamps AND token/cost totals.
@@ -4359,10 +4360,10 @@ def _maybe_swap_active_block_to_canonical(
     if block_end_utc <= now.astimezone(dt.timezone.utc):
         return
     # Re-aggregate entries over the canonical interval. Build a fresh
-    # Block via ``_build_activity_block`` (mode="auto" matches
-    # ``_group_entries_into_blocks``'s default) so every total stays in
-    # one code path — no field-by-field assignment that could drift if
-    # the dataclass grows new fields.
+    # Block via ``_build_activity_block`` so every total stays in one code
+    # path — no field-by-field assignment that could drift if the dataclass
+    # grows new fields. Thread the caller's ``mode`` so the active block's
+    # cost honors --mode like the main grouping (Session C / Codex F1).
     canonical_entries = [
         e for e in all_entries
         if block_start_utc <= e.timestamp < block_end_utc
@@ -4372,7 +4373,7 @@ def _maybe_swap_active_block_to_canonical(
         block_start_utc,
         block_end_utc,
         now.astimezone(dt.timezone.utc),
-        "auto",
+        mode,
         anchor="recorded",
     )
     blocks[active_idx] = rebuilt
@@ -4541,7 +4542,7 @@ def cmd_daily(args: argparse.Namespace) -> int:
     # fields live on BucketUsage, not on DailyPanelRow. The builder's
     # `_aggregate_daily` call is the same one we used inline.
     view = build_daily_view(all_entries, now_utc=_command_as_of(),
-                            display_tz=tz)
+                            display_tz=tz, mode=args.mode)
     # `_aggregate_daily` returned ascending order; build_daily_view stores
     # `aggregated` newest-first. CLI's default order is ascending, so
     # re-reverse to match the prior on-the-wire shape.
@@ -4628,7 +4629,7 @@ def cmd_monthly(args: argparse.Namespace) -> int:
     # Pass a large `n` so the CLI's `--since`/`--until` window controls
     # how many months render (the dashboard caps at n=12; CLI doesn't).
     view = build_monthly_view(all_entries, now_utc=_command_as_of(),
-                              n=10**6, display_tz=tz)
+                              n=10**6, display_tz=tz, mode=args.mode)
     # The view stores `aggregated` newest-first; CLI default is asc.
     months = list(reversed(view.aggregated))
 
@@ -4745,7 +4746,7 @@ def cmd_weekly(args: argparse.Namespace) -> int:
     # assertions stay aligned.
     view = build_weekly_view(
         conn, all_entries, weeks=weeks, now_utc=now_utc,
-        display_tz=args._resolved_tz, as_of_utc=as_of_utc,
+        display_tz=args._resolved_tz, as_of_utc=as_of_utc, mode=args.mode,
     )
     buckets = list(reversed(view.aggregated))
     overlay = list(reversed(view.overlay))
@@ -5973,6 +5974,7 @@ def cmd_session(args: argparse.Namespace) -> int:
     # files collapses to ONE entry in BOTH tuples).
     view = build_sessions_view(
         entries, now_utc=_command_as_of(), limit=None, display_tz=tz,
+        mode=args.mode,
     )
     sessions = list(view.aggregated)
 
@@ -9783,6 +9785,36 @@ def _argparse_has_arg(parser, option_string: str) -> bool:
     return False
 
 
+def _add_mode_arg(parser, *, noop: bool = False) -> None:
+    """Add ccusage's -m/--mode {auto,calculate,display} cost-source flag.
+
+    Standalone (not folded into _add_ccusage_alias_args) so it lands only
+    on the six Session-C reporting commands and never collides with
+    range-cost, which defines its own -m/--mode.
+
+    noop=True (five-hour-blocks only): the flag is accepted for surface
+    parity with `blocks` but does not alter numbers — that command's cost
+    is the authoritative materialized five_hour_blocks.total_cost_usd
+    computed at record-time (always auto semantics).
+    """
+    help_real = (
+        "Cost source: auto (recorded costUSD when present, else computed), "
+        "calculate (always compute from embedded pricing), display "
+        "(recorded costUSD only; $0 when absent). Default: auto."
+    )
+    help_noop = (
+        "Accepted for ccusage drop-in compat; no-op here — five-hour-blocks "
+        "cost is the authoritative materialized per-block value computed at "
+        "record-time. Default: auto."
+    )
+    parser.add_argument(
+        "-m", "--mode",
+        default="auto",
+        choices=["auto", "calculate", "display"],
+        help=help_noop if noop else help_real,
+    )
+
+
 def _add_ccusage_alias_args(parser, *, ansi_emit: bool) -> None:
     """Attach the Session A ccusage alias surface to a Claude-cmd subparser.
 
@@ -10137,6 +10169,7 @@ def _build_daily_parser(subparsers, name, *, help_text, xref):
              "Overrides config display.tz for this call.",
     )
     _add_ccusage_alias_args(p, ansi_emit=False)
+    _add_mode_arg(p)
     _add_share_args(p)
     p.set_defaults(func=cmd_daily)
     return p
@@ -10195,6 +10228,7 @@ def _build_monthly_parser(subparsers, name, *, help_text, xref):
              "Overrides config display.tz for this call.",
     )
     _add_ccusage_alias_args(p, ansi_emit=False)
+    _add_mode_arg(p)
     _add_share_args(p)
     p.set_defaults(func=cmd_monthly)
     return p
@@ -10235,6 +10269,7 @@ def _build_weekly_parser(subparsers, name, *, help_text, xref):
                    help="Display timezone: local, utc, or IANA name. "
                         "Overrides config display.tz for this call.")
     _add_ccusage_alias_args(p, ansi_emit=False)
+    _add_mode_arg(p)
     _add_share_args(p)
     p.set_defaults(func=cmd_weekly)
     return p
@@ -10286,6 +10321,7 @@ def _build_session_parser(subparsers, name, *, help_text, xref):
              "Unknown id → exit 0 with the empty-render branch.",
     )
     _add_ccusage_alias_args(p, ansi_emit=False)
+    _add_mode_arg(p)
     _add_share_args(p)
     p.set_defaults(func=cmd_session)
     return p
@@ -10340,6 +10376,7 @@ def _build_blocks_parser(subparsers, name, *, help_text, xref):
              "Overrides config display.tz for this call.",
     )
     _add_ccusage_alias_args(p, ansi_emit=False)
+    _add_mode_arg(p)
     p.set_defaults(func=cmd_blocks)
     return p
 
@@ -11266,6 +11303,7 @@ def build_parser() -> argparse.ArgumentParser:
     # guard. The helper's --color add lands as a parsed-and-ignored
     # no-op (the renderer emits plain text).
     _add_ccusage_alias_args(fhb, ansi_emit=False)
+    _add_mode_arg(fhb, noop=True)
     _add_share_args(fhb)
     fhb.set_defaults(func=cmd_five_hour_blocks)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctally",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.",
   "homepage": "https://github.com/omrikais/cctally",
   "repository": {