cctally 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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
+- **`cctally claude <cmd>` and `cctally codex <cmd>` subgroup commands** let you paste ccusage's hierarchical syntax verbatim — `cctally claude {daily,monthly,weekly,session,blocks}` is a drop-in for `ccusage claude <cmd>`, and `cctally codex {daily,monthly,session,weekly}` for `ccusage codex <cmd>` (`codex weekly` is a cctally extension; upstream has none). Each subgroup leaf routes to the exact same engine as its flat form, so the table / `--json` / exit code are byte-identical — only `--help` adds a one-line alias/canonical cross-reference. The flat forms (`cctally daily`, `cctally codex-daily`, …) remain fully supported as back-compat aliases, with no deprecation warning. (#86)
+
 ## [1.14.0] - 2026-05-26
 
 ### Added

package/README.md

@@ -113,7 +113,7 @@ For status-line integration, alerts, and configuration, see [docs/installation.m
 
 ## What cctally adds
 
-`cctally` started as a local-first replacement for [`ccusage`](https://github.com/ryoppippi/ccusage), and it stays compatible at the level of common CLI flows (`daily`, `monthly`, `weekly`, `session`, `blocks`). Beyond that, it adds:
+`cctally` started as a local-first replacement for [`ccusage`](https://github.com/ryoppippi/ccusage), and it stays compatible at the level of common CLI flows (`daily`, `monthly`, `weekly`, `session`, `blocks`). Paste from ccusage verbatim: `cctally claude <cmd>` is a drop-in for `ccusage claude <cmd>` (and `cctally codex <cmd>` for `ccusage codex <cmd>`), with the flat forms (`cctally daily`, `cctally codex-daily`, …) kept as aliases. Beyond that, it adds:
 
 - **Live web dashboard.** Nine-panel SSE-driven view at `localhost:8789` (current week, forecast, trend, sessions, weekly, monthly, blocks, daily, recent alerts), with per-panel modals, a mobile layout, threshold alerts, and a settings drawer.
 - **TUI live mode.** The same data inside your terminal (`cctally tui`; requires the optional `rich` package).
@@ -123,7 +123,7 @@ For status-line integration, alerts, and configuration, see [docs/installation.m
 - **5-hour block analytics.** Per-block usage with model and project breakdowns (`cctally five-hour-blocks --breakdown=model`).
 - **Time-window diff.** Compare two windows with model and project decomposition (`cctally diff`).
 - **Project rollup.** Usage by Git project (`cctally project`).
-- **Codex parity.** Drop-in replacements for `ccusage-codex daily / monthly / session`, plus an added `cctally codex-weekly` rollup (upstream has no `codex weekly`).
+- **Codex parity.** `cctally codex daily / monthly / session` are drop-ins for `ccusage codex daily / monthly / session`; the flat `codex-*` forms (drop-ins for the standalone `ccusage-codex` binary) remain as aliases, plus an added `cctally codex weekly` / `cctally codex-weekly` rollup (upstream has no `codex weekly`).
 - **Persistent SQLite.** Week-over-week comparisons survive across runs.
 
 **On speed.** Pricing is embedded and computed at query time from a delta-tail SQLite cache (`~/.local/share/cctally/cache.db`), with no shell-outs. First-table latency on 30 days of session data: **~2.6s (cctally) vs ~31s (ccusage)**, about 12× faster. Measured by `bench/cctally-vs-ccusage.sh` on macOS arm64, 2026-05-05; your numbers will vary.[^bench]

package/bin/_cctally_db.py

@@ -2371,6 +2371,10 @@ def _recompute_banner_should_emit(
           confuses scripted pipelines. Banner still lands on the
           next interactive non-report command (``report``,
           ``weekly``, ``percent-breakdown``, etc.) once on upgrade.
+          Subgroup forms (``cctally claude/codex <cmd>``, issue #86
+          Session B) carry the source group in ``argv[1]`` and the
+          leaf in ``argv[2]``; we resolve the leaf so suppression is
+          byte-identical to the flat alias.
 
     Returns True iff the banner should be printed. Defensive: any
     error reading ``sys.argv`` falls back to "don't print" — silence
@@ -2388,6 +2392,14 @@ def _recompute_banner_should_emit(
         return False
     try:
         argv1 = sys.argv[1] if len(sys.argv) > 1 else None
+        # Subgroup forms (`cctally claude <cmd>` / `cctally codex <cmd>`) carry
+        # the source group in argv[1]; the suppression key is the leaf command
+        # in argv[2]. Resolve it so the recompute banner suppresses identically
+        # to the flat alias (issue #86 Session B; matches the args.command leaf
+        # resolution used by the error-sentinel banner). Purely additive — flat
+        # invocations (argv1 not in {claude,codex}) are byte-identical to before.
+        if argv1 in ("claude", "codex") and len(sys.argv) > 2:
+            argv1 = sys.argv[2]
     except Exception:
         argv1 = None
     if argv1 in _BANNER_SUPPRESSED_COMMANDS:

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.
 
@@ -9887,6 +9919,70 @@ def _add_ccusage_alias_args(parser, *, ansi_emit: bool) -> None:
         )
 
 
+def _add_codex_shared_args(parser: argparse.ArgumentParser) -> None:
+    """Register upstream `ccusage-codex sharedArgs` on a codex subparser.
+
+    Upstream sharedArgs (node_modules/@ccusage/codex/dist/index.js):
+      --timezone/-z, --locale/-l, --compact, --color, --noColor,
+      --offline/--no-offline.
+
+    Honored here: --timezone (dates + aggregation buckets) and
+    --compact (table layout). Accepted-but-no-op (stored on the
+    namespace for drop-in parity with upstream scripts): --locale
+    (we don't locale-format dates), --color / --noColor (we don't
+    emit ANSI codes today). --offline is accepted as a no-op too
+    (we are always offline); it uses BooleanOptionalAction so
+    `--no-offline` also parses cleanly. `-O` is kept as the short
+    form for offline for backward compat with earlier builds.
+    """
+    parser.add_argument(
+        "-z", "--timezone", default=None, metavar="TZ",
+        help="IANA timezone for date bucketing and Date/Last Activity cells.",
+    )
+    parser.add_argument(
+        "-l", "--locale", default=None, metavar="LOCALE",
+        help="Accepted for drop-in compat; no-op (dates are not locale-formatted).",
+    )
+    parser.add_argument(
+        "--compact", action="store_true",
+        help="Force compact table layout regardless of terminal width.",
+    )
+    parser.add_argument(
+        "--color", action="store_true",
+        help="Accepted for drop-in compat; no-op today (no ANSI escapes are emitted).",
+    )
+    parser.add_argument(
+        "--noColor", action="store_true", dest="no_color",
+        help="Accepted for drop-in compat; no-op today (no ANSI escapes are emitted).",
+    )
+    parser.add_argument(
+        "-O", "--offline", action=argparse.BooleanOptionalAction, default=False,
+        help="Accepted for drop-in compat with ccusage-codex; we are always offline.",
+    )
+    parser.add_argument(
+        "--tz", default=None, type=_argparse_tz, metavar="TZ",
+        help="Display timezone: local, utc, or IANA name. Overrides "
+             "config display.tz for this call. Takes precedence over "
+             "upstream's --timezone for drop-in parity.",
+    )
+    # Issue #92: codex parity for the #89 --debug surface. Codex JSONL
+    # has no recorded costUSD to diff against, so the report is the
+    # codex variant ("Codex Pricing Debug Report": totals + top-N
+    # highest computed-cost entries), wired via
+    # _emit_codex_debug_samples_if_set in each cmd_codex_* body.
+    parser.add_argument(
+        "-d", "--debug", action="store_true",
+        help="Emit a stderr 'Codex Pricing Debug Report' (totals + "
+             "the N highest computed-cost sample entries).",
+    )
+    parser.add_argument(
+        "--debug-samples", type=_nonneg_int, default=5, metavar="N",
+        help="Cap on top-entry sample rows in the --debug report "
+             "(default 5; N=0 suppresses the sample block; "
+             "negatives rejected at parse time).",
+    )
+
+
 def _add_share_args(parser, *, has_status_line: bool = False) -> None:
     """Attach shareable-reports flags + format/json mutex to a subparser.
 
@@ -10015,6 +10111,399 @@ def _share_validate_args(args) -> None:
         sys.exit(2)
 
 
+def _build_daily_parser(subparsers, name, *, help_text, xref):
+    """Build the `daily` leaf parser (issue #86 Session B; routes to cmd_daily).
+
+    Build-once, register-twice: this body is the verbatim former inline `daily`
+    construction, parameterized only by `name`, the parent-list `help_text`, and
+    the `xref` appended to `description` (renders on `cctally <name> --help`).
+    """
+    p = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description="Show usage grouped by date, matching upstream ccusage daily output."
+                    "\n\n" + xref,
+        epilog=textwrap.dedent("""\
+            Examples:
+              cctally daily --since 20260414
+              cctally daily --since 20260410 --until 20260416
+              cctally daily --since 20260414 --breakdown
+              cctally daily --since 20260414 --json
+              cctally daily --order desc
+        """),
+    )
+    p.add_argument(
+        "-s", "--since",
+        default=None,
+        metavar="YYYYMMDD",
+        help="Filter from date (inclusive).",
+    )
+    p.add_argument(
+        "-u", "--until",
+        default=None,
+        metavar="YYYYMMDD",
+        help="Filter until date (inclusive).",
+    )
+    p.add_argument(
+        "-b", "--breakdown",
+        action="store_true",
+        help="Show per-model cost breakdown sub-rows.",
+    )
+    p.add_argument(
+        "-o", "--order",
+        choices=("asc", "desc"),
+        default="asc",
+        help="Sort direction by date (default: asc).",
+    )
+    p.add_argument(
+        "--reveal-projects",
+        action="store_true",
+        dest="reveal_projects",
+        help="In --format output, show real project basenames instead of "
+             "the default project-1, project-2, ... anonymization.",
+    )
+    p.add_argument(
+        "--tz", default=None, type=_argparse_tz, metavar="TZ",
+        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_daily)
+    return p
+
+
+def _build_monthly_parser(subparsers, name, *, help_text, xref):
+    """Build the `monthly` leaf parser (issue #86 Session B; routes to cmd_monthly)."""
+    p = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description="Show usage grouped by calendar month, matching upstream ccusage monthly output."
+                    "\n\n" + xref,
+        epilog=textwrap.dedent("""\
+            Examples:
+              cctally monthly --since 20260101
+              cctally monthly --since 20260101 --until 20260331
+              cctally monthly --since 20260101 --breakdown
+              cctally monthly --since 20260101 --json
+              cctally monthly --order desc
+        """),
+    )
+    p.add_argument(
+        "-s", "--since",
+        default=None,
+        metavar="YYYYMMDD",
+        help="Filter from date (inclusive).",
+    )
+    p.add_argument(
+        "-u", "--until",
+        default=None,
+        metavar="YYYYMMDD",
+        help="Filter until date (inclusive).",
+    )
+    p.add_argument(
+        "-b", "--breakdown",
+        action="store_true",
+        help="Show per-model cost breakdown sub-rows.",
+    )
+    p.add_argument(
+        "-o", "--order",
+        choices=("asc", "desc"),
+        default="asc",
+        help="Sort direction by month (default: asc).",
+    )
+    p.add_argument(
+        "--reveal-projects",
+        action="store_true",
+        dest="reveal_projects",
+        help="In --format output, show real project basenames instead of "
+             "the default project-1, project-2, ... anonymization.",
+    )
+    p.add_argument(
+        "--tz", default=None, type=_argparse_tz, metavar="TZ",
+        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_monthly)
+    return p
+
+
+def _build_weekly_parser(subparsers, name, *, help_text, xref):
+    """Build the `weekly` leaf parser (issue #86 Session B; routes to cmd_weekly)."""
+    p = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description="Show Claude usage grouped by subscription week. Boundaries are anchored "
+                    "to weekly_usage_snapshots.week_start_at with 7-day-cadence extrapolation "
+                    "for pre-snapshot history. Columns extend daily/monthly's set with Used % "
+                    "and $/1%."
+                    "\n\n" + xref,
+        epilog=textwrap.dedent("""\
+            Examples:
+              cctally weekly
+              cctally weekly --since 20260101
+              cctally weekly --breakdown
+              cctally weekly --json
+              cctally weekly --order desc
+        """),
+    )
+    p.add_argument("-s", "--since", default=None, metavar="YYYYMMDD",
+                   help="Filter from date (inclusive).")
+    p.add_argument("-u", "--until", default=None, metavar="YYYYMMDD",
+                   help="Filter until date (inclusive).")
+    p.add_argument("-b", "--breakdown", action="store_true",
+                   help="Show per-model cost breakdown sub-rows.")
+    p.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
+                   help="Sort direction by week (default: asc).")
+    p.add_argument("--reveal-projects", action="store_true", dest="reveal_projects",
+                   help="In --format output, show real project basenames instead of "
+                        "the default project-1, project-2, ... anonymization.")
+    p.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
+                   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
+
+
+def _build_session_parser(subparsers, name, *, help_text, xref):
+    """Build the `session` leaf parser (issue #86 Session B; routes to cmd_session)."""
+    p = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description="Show Claude usage grouped by JSONL sessionId. Resumed sessions (same "
+                    "sessionId across multiple files) collapse into one row. 11-column "
+                    "layout paralleling codex-session."
+                    "\n\n" + xref,
+        epilog=textwrap.dedent("""\
+            Examples:
+              cctally session
+              cctally session --since 20260401
+              cctally session --since 20260401 --breakdown
+              cctally session --json
+              cctally session --order desc
+        """),
+    )
+    p.add_argument("-s", "--since", default=None, metavar="YYYYMMDD",
+                   help="Filter from date (inclusive).")
+    p.add_argument("-u", "--until", default=None, metavar="YYYYMMDD",
+                   help="Filter until date (inclusive).")
+    p.add_argument("-b", "--breakdown", action="store_true",
+                   help="Show per-model cost breakdown sub-rows.")
+    p.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
+                   help="Sort direction by last activity (default: asc — earliest first).")
+    p.add_argument("--reveal-projects", action="store_true", dest="reveal_projects",
+                   help="In --format output, show real project basenames instead of "
+                        "the default project-1, project-2, ... anonymization.")
+    p.add_argument("--top-n", type=int, default=15, dest="top_n",
+                   metavar="N",
+                   help="In --format output, cap rows to top N by cost (default: 15). "
+                        "Must be >= 1; values above 50 emit a readability warning. "
+                        "Has no effect on terminal/JSON output.")
+    p.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
+                   help="Display timezone: local, utc, or IANA name. "
+                        "Overrides config display.tz for this call.")
+    p.add_argument(
+        "-i", "--id", default=None, metavar="SESSION_ID", dest="id",
+        help="Filter to a single session by exact-string sessionId. "
+             "Match is against the post-resume-merge id (sessions "
+             "resumed across multiple JSONL files collapse to one id). "
+             "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
+
+
+def _build_blocks_parser(subparsers, name, *, help_text, xref):
+    """Build the `blocks` leaf parser (issue #86 Session B; routes to cmd_blocks).
+
+    Note: `blocks` intentionally has NO `_add_share_args` (matches the former
+    inline block — it is not part of the shareable-output flag surface).
+    """
+    p = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description="Show usage grouped by 5-hour session blocks, matching upstream ccusage blocks output."
+                    "\n\n" + xref,
+        epilog=textwrap.dedent("""\
+            Examples:
+              cctally blocks --since 20260414
+              cctally blocks --since 20260410 --until 20260416
+              cctally blocks --since 20260414 --breakdown
+              cctally blocks --since 20260414 --json
+        """),
+    )
+    p.add_argument(
+        "-s", "--since",
+        default=None,
+        metavar="YYYYMMDD",
+        help="Filter from date (inclusive).",
+    )
+    p.add_argument(
+        "-u", "--until",
+        default=None,
+        metavar="YYYYMMDD",
+        help="Filter until date (inclusive).",
+    )
+    p.add_argument(
+        "-b", "--breakdown",
+        action="store_true",
+        help="Show per-model cost breakdown.",
+    )
+    p.add_argument(
+        "--json",
+        action="store_true",
+        dest="json",
+        help="Output JSON matching upstream ccusage blocks format.",
+    )
+    p.add_argument(
+        "--tz", default=None, type=_argparse_tz, metavar="TZ",
+        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)
+    p.set_defaults(func=cmd_blocks)
+    return p
+
+
+def _build_codex_daily_parser(subparsers, name, *, help_text, xref):
+    """Build the `codex-daily` leaf parser (issue #86 Session B; routes to cmd_codex_daily)."""
+    p = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description="Show Codex usage grouped by date, matching upstream ccusage-codex daily output."
+                    "\n\n" + xref,
+        epilog=textwrap.dedent("""\
+            Examples:
+              cctally codex-daily --since 20260401
+              cctally codex-daily --since 20260401 --breakdown
+              cctally codex-daily --since 20260401 --json
+              cctally codex-daily --order desc
+        """),
+    )
+    p.add_argument("-s", "--since", default=None, metavar="YYYY-MM-DD",
+                   help="Filter from date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
+    p.add_argument("-u", "--until", default=None, metavar="YYYY-MM-DD",
+                   help="Filter until date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
+    p.add_argument("-b", "--breakdown", action="store_true",
+                   help="Show per-model cost breakdown sub-rows.")
+    p.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
+                   help="Sort direction by date (default: asc).")
+    p.add_argument("--json", action="store_true", dest="json",
+                   help="Output JSON matching upstream ccusage-codex daily format.")
+    _add_codex_shared_args(p)
+    p.set_defaults(func=cmd_codex_daily)
+    return p
+
+
+def _build_codex_monthly_parser(subparsers, name, *, help_text, xref):
+    """Build the `codex-monthly` leaf parser (issue #86 Session B; routes to cmd_codex_monthly)."""
+    p = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description="Show Codex usage grouped by calendar month, matching upstream ccusage-codex monthly output."
+                    "\n\n" + xref,
+        epilog=textwrap.dedent("""\
+            Examples:
+              cctally codex-monthly --since 20260101
+              cctally codex-monthly --breakdown
+              cctally codex-monthly --json
+        """),
+    )
+    p.add_argument("-s", "--since", default=None, metavar="YYYY-MM-DD",
+                   help="Filter from date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
+    p.add_argument("-u", "--until", default=None, metavar="YYYY-MM-DD",
+                   help="Filter until date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
+    p.add_argument("-b", "--breakdown", action="store_true",
+                   help="Show per-model cost breakdown sub-rows.")
+    p.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
+                   help="Sort direction by month (default: asc).")
+    p.add_argument("--json", action="store_true", dest="json",
+                   help="Output JSON matching upstream ccusage-codex monthly format.")
+    _add_codex_shared_args(p)
+    p.set_defaults(func=cmd_codex_monthly)
+    return p
+
+
+def _build_codex_weekly_parser(subparsers, name, *, help_text, xref):
+    """Build the `codex-weekly` leaf parser (issue #86 Session B; routes to cmd_codex_weekly)."""
+    p = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description="Show Codex usage grouped by week. Week-start day is read from config.json "
+                    "(collector.week_start, Monday default). Not a ccusage-codex drop-in — "
+                    "upstream has no `codex weekly` command."
+                    "\n\n" + xref,
+        epilog=textwrap.dedent("""\
+            Examples:
+              cctally codex-weekly
+              cctally codex-weekly --since 20260301
+              cctally codex-weekly --breakdown
+              cctally codex-weekly --json
+              cctally codex-weekly --order desc
+        """),
+    )
+    p.add_argument("-s", "--since", default=None, metavar="YYYY-MM-DD",
+                   help="Filter from date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
+    p.add_argument("-u", "--until", default=None, metavar="YYYY-MM-DD",
+                   help="Filter until date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
+    p.add_argument("-b", "--breakdown", action="store_true",
+                   help="Show per-model cost breakdown sub-rows.")
+    p.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
+                   help="Sort direction by week (default: asc).")
+    p.add_argument("--json", action="store_true", dest="json",
+                   help="Output JSON.")
+    _add_codex_shared_args(p)
+    p.set_defaults(func=cmd_codex_weekly)
+    return p
+
+
+def _build_codex_session_parser(subparsers, name, *, help_text, xref):
+    """Build the `codex-session` leaf parser (issue #86 Session B; routes to cmd_codex_session)."""
+    p = subparsers.add_parser(
+        name,
+        help=help_text,
+        formatter_class=CLIHelpFormatter,
+        description="Show Codex usage grouped by session, matching upstream ccusage-codex session output."
+                    "\n\n" + xref,
+        epilog=textwrap.dedent("""\
+            Examples:
+              cctally codex-session
+              cctally codex-session --since 20260401
+              cctally codex-session --json
+        """),
+    )
+    p.add_argument("-s", "--since", default=None, metavar="YYYY-MM-DD",
+                   help="Filter from date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
+    p.add_argument("-u", "--until", default=None, metavar="YYYY-MM-DD",
+                   help="Filter until date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
+    p.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
+                   help="Sort direction by last activity (default: asc — earliest first).")
+    p.add_argument("--json", action="store_true", dest="json",
+                   help="Output JSON matching upstream ccusage-codex session format.")
+    _add_codex_shared_args(p)
+    p.set_defaults(func=cmd_codex_session)
+    return p
+
+
 def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(
         prog="cctally",
@@ -10747,49 +11236,10 @@ def build_parser() -> argparse.ArgumentParser:
     rc.set_defaults(func=cmd_range_cost)
 
     # -- blocks --
-    bl = sub.add_parser(
-        "blocks",
-        help="Show usage report grouped by 5-hour session blocks",
-        formatter_class=CLIHelpFormatter,
-        description="Show usage grouped by 5-hour session blocks, matching upstream ccusage blocks output.",
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally blocks --since 20260414
-              cctally blocks --since 20260410 --until 20260416
-              cctally blocks --since 20260414 --breakdown
-              cctally blocks --since 20260414 --json
-        """),
-    )
-    bl.add_argument(
-        "-s", "--since",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter from date (inclusive).",
-    )
-    bl.add_argument(
-        "-u", "--until",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter until date (inclusive).",
-    )
-    bl.add_argument(
-        "-b", "--breakdown",
-        action="store_true",
-        help="Show per-model cost breakdown.",
-    )
-    bl.add_argument(
-        "--json",
-        action="store_true",
-        dest="json",
-        help="Output JSON matching upstream ccusage blocks format.",
-    )
-    bl.add_argument(
-        "--tz", default=None, type=_argparse_tz, metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    _add_ccusage_alias_args(bl, ansi_emit=False)
-    bl.set_defaults(func=cmd_blocks)
+    _build_blocks_parser(
+        sub, "blocks",
+        help_text="Show usage report grouped by 5-hour session blocks",
+        xref="Alias of `cctally claude blocks` (the canonical form).")
 
     # -- five-hour-blocks --
     fhb = sub.add_parser(
@@ -10853,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)
 
@@ -10875,319 +11326,46 @@ def build_parser() -> argparse.ArgumentParser:
     p_cache_sync.set_defaults(func=cmd_cache_sync)
 
     # -- daily --
-    dy = sub.add_parser(
-        "daily",
-        help="Show usage report grouped by date",
-        formatter_class=CLIHelpFormatter,
-        description="Show usage grouped by date, matching upstream ccusage daily output.",
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally daily --since 20260414
-              cctally daily --since 20260410 --until 20260416
-              cctally daily --since 20260414 --breakdown
-              cctally daily --since 20260414 --json
-              cctally daily --order desc
-        """),
-    )
-    dy.add_argument(
-        "-s", "--since",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter from date (inclusive).",
-    )
-    dy.add_argument(
-        "-u", "--until",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter until date (inclusive).",
-    )
-    dy.add_argument(
-        "-b", "--breakdown",
-        action="store_true",
-        help="Show per-model cost breakdown sub-rows.",
-    )
-    dy.add_argument(
-        "-o", "--order",
-        choices=("asc", "desc"),
-        default="asc",
-        help="Sort direction by date (default: asc).",
-    )
-    dy.add_argument(
-        "--reveal-projects",
-        action="store_true",
-        dest="reveal_projects",
-        help="In --format output, show real project basenames instead of "
-             "the default project-1, project-2, ... anonymization.",
-    )
-    dy.add_argument(
-        "--tz", default=None, type=_argparse_tz, metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    _add_ccusage_alias_args(dy, ansi_emit=False)
-    _add_share_args(dy)
-    dy.set_defaults(func=cmd_daily)
+    _build_daily_parser(
+        sub, "daily",
+        help_text="Show usage report grouped by date",
+        xref="Alias of `cctally claude daily` (the canonical form).")
 
     # -- monthly --
-    mo = sub.add_parser(
-        "monthly",
-        help="Show usage report grouped by month",
-        formatter_class=CLIHelpFormatter,
-        description="Show usage grouped by calendar month, matching upstream ccusage monthly output.",
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally monthly --since 20260101
-              cctally monthly --since 20260101 --until 20260331
-              cctally monthly --since 20260101 --breakdown
-              cctally monthly --since 20260101 --json
-              cctally monthly --order desc
-        """),
-    )
-    mo.add_argument(
-        "-s", "--since",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter from date (inclusive).",
-    )
-    mo.add_argument(
-        "-u", "--until",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter until date (inclusive).",
-    )
-    mo.add_argument(
-        "-b", "--breakdown",
-        action="store_true",
-        help="Show per-model cost breakdown sub-rows.",
-    )
-    mo.add_argument(
-        "-o", "--order",
-        choices=("asc", "desc"),
-        default="asc",
-        help="Sort direction by month (default: asc).",
-    )
-    mo.add_argument(
-        "--reveal-projects",
-        action="store_true",
-        dest="reveal_projects",
-        help="In --format output, show real project basenames instead of "
-             "the default project-1, project-2, ... anonymization.",
-    )
-    mo.add_argument(
-        "--tz", default=None, type=_argparse_tz, metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    _add_ccusage_alias_args(mo, ansi_emit=False)
-    _add_share_args(mo)
-    mo.set_defaults(func=cmd_monthly)
+    _build_monthly_parser(
+        sub, "monthly",
+        help_text="Show usage report grouped by month",
+        xref="Alias of `cctally claude monthly` (the canonical form).")
 
     # -- weekly --
-    we = sub.add_parser(
-        "weekly",
-        help="Show usage grouped by subscription week (with Used %% and $/1%%)",
-        formatter_class=CLIHelpFormatter,
-        description="Show Claude usage grouped by subscription week. Boundaries are anchored "
-                    "to weekly_usage_snapshots.week_start_at with 7-day-cadence extrapolation "
-                    "for pre-snapshot history. Columns extend daily/monthly's set with Used % "
-                    "and $/1%.",
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally weekly
-              cctally weekly --since 20260101
-              cctally weekly --breakdown
-              cctally weekly --json
-              cctally weekly --order desc
-        """),
-    )
-    we.add_argument("-s", "--since", default=None, metavar="YYYYMMDD",
-                    help="Filter from date (inclusive).")
-    we.add_argument("-u", "--until", default=None, metavar="YYYYMMDD",
-                    help="Filter until date (inclusive).")
-    we.add_argument("-b", "--breakdown", action="store_true",
-                    help="Show per-model cost breakdown sub-rows.")
-    we.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
-                    help="Sort direction by week (default: asc).")
-    we.add_argument("--reveal-projects", action="store_true", dest="reveal_projects",
-                    help="In --format output, show real project basenames instead of "
-                         "the default project-1, project-2, ... anonymization.")
-    we.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
-                    help="Display timezone: local, utc, or IANA name. "
-                         "Overrides config display.tz for this call.")
-    _add_ccusage_alias_args(we, ansi_emit=False)
-    _add_share_args(we)
-    we.set_defaults(func=cmd_weekly)
-
-    # -- codex shared args helper --
-    def _add_codex_shared_args(parser: argparse.ArgumentParser) -> None:
-        """Register upstream `ccusage-codex sharedArgs` on a codex subparser.
-
-        Upstream sharedArgs (node_modules/@ccusage/codex/dist/index.js):
-          --timezone/-z, --locale/-l, --compact, --color, --noColor,
-          --offline/--no-offline.
-
-        Honored here: --timezone (dates + aggregation buckets) and
-        --compact (table layout). Accepted-but-no-op (stored on the
-        namespace for drop-in parity with upstream scripts): --locale
-        (we don't locale-format dates), --color / --noColor (we don't
-        emit ANSI codes today). --offline is accepted as a no-op too
-        (we are always offline); it uses BooleanOptionalAction so
-        `--no-offline` also parses cleanly. `-O` is kept as the short
-        form for offline for backward compat with earlier builds.
-        """
-        parser.add_argument(
-            "-z", "--timezone", default=None, metavar="TZ",
-            help="IANA timezone for date bucketing and Date/Last Activity cells.",
-        )
-        parser.add_argument(
-            "-l", "--locale", default=None, metavar="LOCALE",
-            help="Accepted for drop-in compat; no-op (dates are not locale-formatted).",
-        )
-        parser.add_argument(
-            "--compact", action="store_true",
-            help="Force compact table layout regardless of terminal width.",
-        )
-        parser.add_argument(
-            "--color", action="store_true",
-            help="Accepted for drop-in compat; no-op today (no ANSI escapes are emitted).",
-        )
-        parser.add_argument(
-            "--noColor", action="store_true", dest="no_color",
-            help="Accepted for drop-in compat; no-op today (no ANSI escapes are emitted).",
-        )
-        parser.add_argument(
-            "-O", "--offline", action=argparse.BooleanOptionalAction, default=False,
-            help="Accepted for drop-in compat with ccusage-codex; we are always offline.",
-        )
-        parser.add_argument(
-            "--tz", default=None, type=_argparse_tz, metavar="TZ",
-            help="Display timezone: local, utc, or IANA name. Overrides "
-                 "config display.tz for this call. Takes precedence over "
-                 "upstream's --timezone for drop-in parity.",
-        )
-        # Issue #92: codex parity for the #89 --debug surface. Codex JSONL
-        # has no recorded costUSD to diff against, so the report is the
-        # codex variant ("Codex Pricing Debug Report": totals + top-N
-        # highest computed-cost entries), wired via
-        # _emit_codex_debug_samples_if_set in each cmd_codex_* body.
-        parser.add_argument(
-            "-d", "--debug", action="store_true",
-            help="Emit a stderr 'Codex Pricing Debug Report' (totals + "
-                 "the N highest computed-cost sample entries).",
-        )
-        parser.add_argument(
-            "--debug-samples", type=_nonneg_int, default=5, metavar="N",
-            help="Cap on top-entry sample rows in the --debug report "
-                 "(default 5; N=0 suppresses the sample block; "
-                 "negatives rejected at parse time).",
-        )
+    _build_weekly_parser(
+        sub, "weekly",
+        help_text="Show usage grouped by subscription week (with Used %% and $/1%%)",
+        xref="Alias of `cctally claude weekly` (the canonical form).")
 
     # -- codex-daily --
-    cd = sub.add_parser(
-        "codex-daily",
-        help="Show Codex usage report grouped by date (drop-in for `ccusage-codex daily`)",
-        formatter_class=CLIHelpFormatter,
-        description="Show Codex usage grouped by date, matching upstream ccusage-codex daily output.",
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally codex-daily --since 20260401
-              cctally codex-daily --since 20260401 --breakdown
-              cctally codex-daily --since 20260401 --json
-              cctally codex-daily --order desc
-        """),
-    )
-    cd.add_argument("-s", "--since", default=None, metavar="YYYY-MM-DD",
-                    help="Filter from date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    cd.add_argument("-u", "--until", default=None, metavar="YYYY-MM-DD",
-                    help="Filter until date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    cd.add_argument("-b", "--breakdown", action="store_true",
-                    help="Show per-model cost breakdown sub-rows.")
-    cd.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
-                    help="Sort direction by date (default: asc).")
-    cd.add_argument("--json", action="store_true", dest="json",
-                    help="Output JSON matching upstream ccusage-codex daily format.")
-    _add_codex_shared_args(cd)
-    cd.set_defaults(func=cmd_codex_daily)
+    _build_codex_daily_parser(
+        sub, "codex-daily",
+        help_text="Show Codex usage report grouped by date (drop-in for `ccusage-codex daily`)",
+        xref="Alias of `cctally codex daily` (the canonical form).")
 
     # -- codex-monthly --
-    cmn = sub.add_parser(
-        "codex-monthly",
-        help="Show Codex usage grouped by month (drop-in for `ccusage-codex monthly`)",
-        formatter_class=CLIHelpFormatter,
-        description="Show Codex usage grouped by calendar month, matching upstream ccusage-codex monthly output.",
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally codex-monthly --since 20260101
-              cctally codex-monthly --breakdown
-              cctally codex-monthly --json
-        """),
-    )
-    cmn.add_argument("-s", "--since", default=None, metavar="YYYY-MM-DD",
-                     help="Filter from date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    cmn.add_argument("-u", "--until", default=None, metavar="YYYY-MM-DD",
-                     help="Filter until date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    cmn.add_argument("-b", "--breakdown", action="store_true",
-                     help="Show per-model cost breakdown sub-rows.")
-    cmn.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
-                     help="Sort direction by month (default: asc).")
-    cmn.add_argument("--json", action="store_true", dest="json",
-                     help="Output JSON matching upstream ccusage-codex monthly format.")
-    _add_codex_shared_args(cmn)
-    cmn.set_defaults(func=cmd_codex_monthly)
+    _build_codex_monthly_parser(
+        sub, "codex-monthly",
+        help_text="Show Codex usage grouped by month (drop-in for `ccusage-codex monthly`)",
+        xref="Alias of `cctally codex monthly` (the canonical form).")
 
     # -- codex-weekly --
-    cw = sub.add_parser(
-        "codex-weekly",
-        help="Show Codex usage grouped by week (week-start from config.json)",
-        formatter_class=CLIHelpFormatter,
-        description="Show Codex usage grouped by week. Week-start day is read from config.json "
-                    "(collector.week_start, Monday default). Not a ccusage-codex drop-in — "
-                    "upstream has no `codex weekly` command.",
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally codex-weekly
-              cctally codex-weekly --since 20260301
-              cctally codex-weekly --breakdown
-              cctally codex-weekly --json
-              cctally codex-weekly --order desc
-        """),
-    )
-    cw.add_argument("-s", "--since", default=None, metavar="YYYY-MM-DD",
-                    help="Filter from date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    cw.add_argument("-u", "--until", default=None, metavar="YYYY-MM-DD",
-                    help="Filter until date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    cw.add_argument("-b", "--breakdown", action="store_true",
-                    help="Show per-model cost breakdown sub-rows.")
-    cw.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
-                    help="Sort direction by week (default: asc).")
-    cw.add_argument("--json", action="store_true", dest="json",
-                    help="Output JSON.")
-    _add_codex_shared_args(cw)
-    cw.set_defaults(func=cmd_codex_weekly)
+    _build_codex_weekly_parser(
+        sub, "codex-weekly",
+        help_text="Show Codex usage grouped by week (week-start from config.json)",
+        xref="Alias of `cctally codex weekly` (the canonical form).")
 
     # -- codex-session --
-    cs = sub.add_parser(
-        "codex-session",
-        help="Show Codex usage grouped by session (drop-in for `ccusage-codex session`)",
-        formatter_class=CLIHelpFormatter,
-        description="Show Codex usage grouped by session, matching upstream ccusage-codex session output.",
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally codex-session
-              cctally codex-session --since 20260401
-              cctally codex-session --json
-        """),
-    )
-    cs.add_argument("-s", "--since", default=None, metavar="YYYY-MM-DD",
-                    help="Filter from date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    cs.add_argument("-u", "--until", default=None, metavar="YYYY-MM-DD",
-                    help="Filter until date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    cs.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
-                    help="Sort direction by last activity (default: asc — earliest first).")
-    cs.add_argument("--json", action="store_true", dest="json",
-                    help="Output JSON matching upstream ccusage-codex session format.")
-    _add_codex_shared_args(cs)
-    cs.set_defaults(func=cmd_codex_session)
+    _build_codex_session_parser(
+        sub, "codex-session",
+        help_text="Show Codex usage grouped by session (drop-in for `ccusage-codex session`)",
+        xref="Alias of `cctally codex session` (the canonical form).")
 
     # -- project --
     p_project = sub.add_parser(
@@ -11285,51 +11463,62 @@ def build_parser() -> argparse.ArgumentParser:
     diff_p.set_defaults(func=cmd_diff)
 
     # -- session --
-    se = sub.add_parser(
-        "session",
-        help="Show Claude usage grouped by sessionId (merges resumed-across-files sessions)",
+    _build_session_parser(
+        sub, "session",
+        help_text="Show Claude usage grouped by sessionId (merges resumed-across-files sessions)",
+        xref="Alias of `cctally claude session` (the canonical form).")
+
+    # --- `claude` subgroup (drop-in for `ccusage claude …`); issue #86 Session B ---
+    # Build-once, register-twice: these reuse the same nine builders as the flat
+    # forms above. Nested subparsers reuse dest="command" so args.command resolves
+    # to the leaf name (e.g. "blocks"), keeping banner suppression byte-identical
+    # to the flat form with zero hook-path changes.
+    claude_p = sub.add_parser(
+        "claude",
+        help="Claude-source reports (drop-in for `ccusage claude …`)",
         formatter_class=CLIHelpFormatter,
-        description="Show Claude usage grouped by JSONL sessionId. Resumed sessions (same "
-                    "sessionId across multiple files) collapse into one row. 11-column "
-                    "layout paralleling codex-session.",
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally session
-              cctally session --since 20260401
-              cctally session --since 20260401 --breakdown
-              cctally session --json
-              cctally session --order desc
-        """),
-    )
-    se.add_argument("-s", "--since", default=None, metavar="YYYYMMDD",
-                    help="Filter from date (inclusive).")
-    se.add_argument("-u", "--until", default=None, metavar="YYYYMMDD",
-                    help="Filter until date (inclusive).")
-    se.add_argument("-b", "--breakdown", action="store_true",
-                    help="Show per-model cost breakdown sub-rows.")
-    se.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
-                    help="Sort direction by last activity (default: asc — earliest first).")
-    se.add_argument("--reveal-projects", action="store_true", dest="reveal_projects",
-                    help="In --format output, show real project basenames instead of "
-                         "the default project-1, project-2, ... anonymization.")
-    se.add_argument("--top-n", type=int, default=15, dest="top_n",
-                    metavar="N",
-                    help="In --format output, cap rows to top N by cost (default: 15). "
-                         "Must be >= 1; values above 50 emit a readability warning. "
-                         "Has no effect on terminal/JSON output.")
-    se.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
-                    help="Display timezone: local, utc, or IANA name. "
-                         "Overrides config display.tz for this call.")
-    se.add_argument(
-        "-i", "--id", default=None, metavar="SESSION_ID", dest="id",
-        help="Filter to a single session by exact-string sessionId. "
-             "Match is against the post-resume-merge id (sessions "
-             "resumed across multiple JSONL files collapse to one id). "
-             "Unknown id → exit 0 with the empty-render branch.",
-    )
-    _add_ccusage_alias_args(se, ansi_emit=False)
-    _add_share_args(se)
-    se.set_defaults(func=cmd_session)
+        description="Claude-source usage reports. Each subcommand is a drop-in for the "
+                    "matching `ccusage claude <cmd>` and shares its engine with the "
+                    "top-level `cctally <cmd>` alias.")
+    claude_sub = claude_p.add_subparsers(dest="command", required=True, metavar="<command>")
+    _build_daily_parser(claude_sub, "daily",
+        help_text="Show usage grouped by date",
+        xref="Drop-in for `ccusage claude daily`. Same engine as `cctally daily`.")
+    _build_monthly_parser(claude_sub, "monthly",
+        help_text="Show usage grouped by month",
+        xref="Drop-in for `ccusage claude monthly`. Same engine as `cctally monthly`.")
+    _build_weekly_parser(claude_sub, "weekly",
+        help_text="Show usage grouped by subscription week",
+        xref="Drop-in for `ccusage claude weekly`. Same engine as `cctally weekly`.")
+    _build_session_parser(claude_sub, "session",
+        help_text="Show usage grouped by session",
+        xref="Drop-in for `ccusage claude session`. Same engine as `cctally session`.")
+    _build_blocks_parser(claude_sub, "blocks",
+        help_text="Show usage grouped by 5-hour session blocks",
+        xref="Drop-in for `ccusage claude blocks`. Same engine as `cctally blocks`.")
+
+    # --- `codex` subgroup (drop-in for `ccusage codex …`); issue #86 Session B ---
+    codex_p = sub.add_parser(
+        "codex",
+        help="Codex-source reports (drop-in for `ccusage codex …`)",
+        formatter_class=CLIHelpFormatter,
+        description="Codex-source usage reports. daily/monthly/session are drop-ins for "
+                    "`ccusage codex <cmd>`; weekly is a cctally extension. Each shares its "
+                    "engine with the matching `cctally codex-<cmd>` alias.")
+    codex_sub = codex_p.add_subparsers(dest="command", required=True, metavar="<command>")
+    _build_codex_daily_parser(codex_sub, "daily",
+        help_text="Show Codex usage grouped by date",
+        xref="Drop-in for `ccusage codex daily`. Same engine as `cctally codex-daily`.")
+    _build_codex_monthly_parser(codex_sub, "monthly",
+        help_text="Show Codex usage grouped by month",
+        xref="Drop-in for `ccusage codex monthly`. Same engine as `cctally codex-monthly`.")
+    _build_codex_session_parser(codex_sub, "session",
+        help_text="Show Codex usage grouped by session",
+        xref="Drop-in for `ccusage codex session`. Same engine as `cctally codex-session`.")
+    _build_codex_weekly_parser(codex_sub, "weekly",
+        help_text="Show Codex usage grouped by week",
+        xref="cctally extension (no upstream `ccusage codex weekly`). Same engine as "
+             "`cctally codex-weekly`.")
 
     # ---- config (persisted user preferences) ----
     cfg_p = sub.add_parser(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctally",
-  "version": "1.14.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": {