scrollback 0.1.2__tar.gz → 0.2.0__tar.gz

{scrollback-0.1.2 → scrollback-0.2.0}/CHANGELOG.md

@@ -6,6 +6,26 @@ follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-06-30
+
+### Added
+
+- **Cache & reasoning token accounting.** Sessions now carry
+  `tokens_cache_read`, `tokens_cache_write`, and `tokens_reasoning` in
+  addition to input/output/cost. In agentic sessions cache reads often
+  dominate total token volume, so this makes scrollback's usage numbers
+  reconcilable with the agents' own reports:
+  - **opencode** reads the corresponding SQLite columns (tolerant of older
+    databases that lack them).
+  - **Claude Code** now reports usage at all — summed per-turn from each
+    assistant message's `usage` block (previously blank).
+  - **Codex** parses token-count records where the rollout format includes
+    them (best-effort; `None` when absent).
+  - **Aider** has no token data on disk and stays `None`.
+- `stats` shows a `cache` (read/write) line and a `reasoning` line; the web
+  transcript header shows a cache figure; Markdown/HTML/JSON exports include
+  a usage summary.
+
 ## [0.1.2] - 2026-06-30
 
 ### Added
@@ -100,7 +120,8 @@ export it from a CLI and a local web app.
 - Negative pagination arguments are rejected; clearer errors for unknown
   sources, failed exports, and unavailable data sources.
 
-[Unreleased]: https://github.com/a-attia/scrollback/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/a-attia/scrollback/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/a-attia/scrollback/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/a-attia/scrollback/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/a-attia/scrollback/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/a-attia/scrollback/releases/tag/v0.1.0

{scrollback-0.1.2 → scrollback-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scrollback
-Version: 0.1.2
+Version: 0.2.0
 Summary: Navigate, search, copy, and export your AI coding-agent sessions (opencode, Claude Code, ...) from one local, read-only tool.
 Project-URL: Homepage, https://github.com/a-attia/scrollback
 Project-URL: Repository, https://github.com/a-attia/scrollback
@@ -73,13 +73,13 @@ modifies, locks for writing, or uploads your data.
 You can use it two ways. From the **command line**, list, search, and export
 your sessions in a single scriptable tool:
 
-![scrollback listing recent sessions in the terminal.](https://raw.githubusercontent.com/a-attia/scrollback/v0.1.2/assets/screenshots/cli.png)
+![scrollback listing recent sessions in the terminal.](https://raw.githubusercontent.com/a-attia/scrollback/v0.2.0/assets/screenshots/cli.png)
 
 Or open the **local web app** to read a transcript in full — with rendered
 Markdown, syntax-highlighted code, and typeset LaTeX math:
 
 ![The scrollback web app showing a session list beside a transcript with
-rendered Markdown, highlighted code, and typeset equations.](https://raw.githubusercontent.com/a-attia/scrollback/v0.1.2/assets/screenshots/web.png)
+rendered Markdown, highlighted code, and typeset equations.](https://raw.githubusercontent.com/a-attia/scrollback/v0.2.0/assets/screenshots/web.png)
 
 Both views read the same on-disk session stores, so you can jump between
 them freely. (The screenshots above use synthetic demo data.)
@@ -235,6 +235,16 @@ busiest projects. `resume` prints the command to continue a session in its
 own agent (for example `opencode --session <id>` or `claude --resume <id>`),
 with a `cd` into the session's project directory.
 
+**A note on token figures.** Where the source records it, scrollback reports
+tokens in four buckets — *input*, *output*, *cache read*, and *cache write* —
+because they mean different things and are priced very differently. In
+agentic sessions the conversation context is re-sent every turn but served
+from the prompt cache, so **cache reads usually dominate total volume** while
+costing a fraction of fresh input. "Total tokens" is therefore not one
+number; the cost figure (when available) is the most faithful summary of
+consumption. Sources that don't record a given figure show it as blank
+rather than a misleading zero.
+
 ## The web app
 
 `scrollback web` starts a local, read-only browser UI — FastAPI plus a

{scrollback-0.1.2 → scrollback-0.2.0}/README.md

@@ -14,13 +14,13 @@ modifies, locks for writing, or uploads your data.
 You can use it two ways. From the **command line**, list, search, and export
 your sessions in a single scriptable tool:
 
-![scrollback listing recent sessions in the terminal.](https://raw.githubusercontent.com/a-attia/scrollback/v0.1.2/assets/screenshots/cli.png)
+![scrollback listing recent sessions in the terminal.](https://raw.githubusercontent.com/a-attia/scrollback/v0.2.0/assets/screenshots/cli.png)
 
 Or open the **local web app** to read a transcript in full — with rendered
 Markdown, syntax-highlighted code, and typeset LaTeX math:
 
 ![The scrollback web app showing a session list beside a transcript with
-rendered Markdown, highlighted code, and typeset equations.](https://raw.githubusercontent.com/a-attia/scrollback/v0.1.2/assets/screenshots/web.png)
+rendered Markdown, highlighted code, and typeset equations.](https://raw.githubusercontent.com/a-attia/scrollback/v0.2.0/assets/screenshots/web.png)
 
 Both views read the same on-disk session stores, so you can jump between
 them freely. (The screenshots above use synthetic demo data.)
@@ -176,6 +176,16 @@ busiest projects. `resume` prints the command to continue a session in its
 own agent (for example `opencode --session <id>` or `claude --resume <id>`),
 with a `cd` into the session's project directory.
 
+**A note on token figures.** Where the source records it, scrollback reports
+tokens in four buckets — *input*, *output*, *cache read*, and *cache write* —
+because they mean different things and are priced very differently. In
+agentic sessions the conversation context is re-sent every turn but served
+from the prompt cache, so **cache reads usually dominate total volume** while
+costing a fraction of fresh input. "Total tokens" is therefore not one
+number; the cost figure (when available) is the most faithful summary of
+consumption. Sources that don't record a given figure show it as blank
+rather than a misleading zero.
+
 ## The web app
 
 `scrollback web` starts a local, read-only browser UI — FastAPI plus a

{scrollback-0.1.2 → scrollback-0.2.0}/src/scrollback/__init__.py

@@ -5,4 +5,4 @@ coding agents (opencode, Claude Code, ...) through a common adapter
 interface and lets you list, view, search, and export those sessions.
 """
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"

{scrollback-0.1.2 → scrollback-0.2.0}/src/scrollback/cli.py

@@ -211,6 +211,9 @@ def cmd_stats(args: argparse.Namespace) -> int:
             "total_messages": st.total_messages,
             "total_tokens_input": st.total_tokens_input,
             "total_tokens_output": st.total_tokens_output,
+            "total_tokens_cache_read": st.total_tokens_cache_read,
+            "total_tokens_cache_write": st.total_tokens_cache_write,
+            "total_tokens_reasoning": st.total_tokens_reasoning,
             "total_cost": st.total_cost,
             "oldest": st.oldest.isoformat() if st.oldest else None,
             "newest": st.newest.isoformat() if st.newest else None,
@@ -228,6 +231,11 @@ def cmd_stats(args: argparse.Namespace) -> int:
     if st.total_tokens_input or st.total_tokens_output:
         print(f"tokens:   {_fmt_tokens(st.total_tokens_input)} in / "
               f"{_fmt_tokens(st.total_tokens_output)} out")
+    if st.total_tokens_cache_read or st.total_tokens_cache_write:
+        print(f"cache:    {_fmt_tokens(st.total_tokens_cache_read)} read / "
+              f"{_fmt_tokens(st.total_tokens_cache_write)} write")
+    if st.total_tokens_reasoning:
+        print(f"reasoning:{_fmt_tokens(st.total_tokens_reasoning)} tokens")
     if st.total_cost:
         print(f"cost:     ${st.total_cost:.2f}")
     print()
@@ -339,6 +347,9 @@ def cmd_list(args: argparse.Namespace) -> int:
                 "cost": s.cost,
                 "tokens_input": s.tokens_input,
                 "tokens_output": s.tokens_output,
+                "tokens_cache_read": s.tokens_cache_read,
+                "tokens_cache_write": s.tokens_cache_write,
+                "tokens_reasoning": s.tokens_reasoning,
                 "parent_id": s.parent_id,
                 "children": [row(c) for c in s.children],
             }

{scrollback-0.1.2 → scrollback-0.2.0}/src/scrollback/export.py

@@ -26,6 +26,35 @@ def _fmt_dt(dt: datetime | None) -> str:
     return dt.strftime("%Y-%m-%d %H:%M:%S %Z").strip() if dt else "?"
 
 
+def _fmt_tokens(n: int | None) -> str:
+    if not n:
+        return "0"
+    if n < 1000:
+        return str(n)
+    if n < 1_000_000:
+        return f"{n / 1e3:.1f}k"
+    return f"{n / 1e6:.1f}M"
+
+
+def _usage_summary(session: Session) -> str:
+    """A compact one-line usage string, or '' when the source reports none."""
+    s = session
+    if not any((s.tokens_input, s.tokens_output, s.tokens_cache_read,
+                s.tokens_cache_write, s.tokens_reasoning, s.cost)):
+        return ""
+    bits = []
+    if s.tokens_input or s.tokens_output:
+        bits.append(f"{_fmt_tokens(s.tokens_input)} in / {_fmt_tokens(s.tokens_output)} out")
+    if s.tokens_cache_read or s.tokens_cache_write:
+        bits.append(f"cache {_fmt_tokens(s.tokens_cache_read)} read / "
+                    f"{_fmt_tokens(s.tokens_cache_write)} write")
+    if s.tokens_reasoning:
+        bits.append(f"{_fmt_tokens(s.tokens_reasoning)} reasoning")
+    if s.cost:
+        bits.append(f"${s.cost:.2f}")
+    return "; ".join(bits)
+
+
 # -- markdown --------------------------------------------------------------
 
 
@@ -50,6 +79,9 @@ def to_markdown(session: Session, *, include_reasoning: bool = True,
     lines.append(f"- **Created**: {_fmt_dt(session.created)}")
     lines.append(f"- **Updated**: {_fmt_dt(session.updated)}")
     lines.append(f"- **Messages**: {len(session.messages)}")
+    usage = _usage_summary(session)
+    if usage:
+        lines.append(f"- **Usage**: {usage}")
     lines.append("")
     lines.append("---")
     lines.append("")
@@ -211,6 +243,9 @@ def to_html(session: Session, *, include_reasoning: bool = True,
         meta_bits.append(f"model: {session.model}")
     meta_bits.append(f"created: {_fmt_dt(session.created)}")
     meta_bits.append(f"messages: {len(session.messages)}")
+    usage = _usage_summary(session)
+    if usage:
+        meta_bits.append(f"usage: {usage}")
     meta = " &middot; ".join(_html.escape(b) for b in meta_bits)
 
     body_parts: list[str] = []

{scrollback-0.1.2 → scrollback-0.2.0}/src/scrollback/models.py

@@ -111,10 +111,17 @@ class Session:
     agent: str | None = None
     parent_id: str | None = None
     message_count: int | None = None
-    # Usage accounting (opencode tracks these; None when unknown).
+    # Usage accounting (None when the source does not report a given figure).
+    # `tokens_input` / `tokens_output` are fresh (uncached) prompt + generated
+    # tokens; the cache figures track prompt-cache reuse (large in agentic
+    # sessions and priced very differently); `tokens_reasoning` is the portion
+    # of output spent on hidden reasoning, where the source distinguishes it.
     cost: float | None = None
     tokens_input: int | None = None
     tokens_output: int | None = None
+    tokens_cache_read: int | None = None
+    tokens_cache_write: int | None = None
+    tokens_reasoning: int | None = None
     # Children populated when subagent folding is enabled.
     children: tuple["Session", ...] = ()
     messages: tuple[Message, ...] = ()

{scrollback-0.1.2 → scrollback-0.2.0}/src/scrollback/serialize.py

@@ -36,6 +36,9 @@ def session_summary(s: Session) -> dict[str, Any]:
         "cost": s.cost,
         "tokens_input": s.tokens_input,
         "tokens_output": s.tokens_output,
+        "tokens_cache_read": s.tokens_cache_read,
+        "tokens_cache_write": s.tokens_cache_write,
+        "tokens_reasoning": s.tokens_reasoning,
         "git_branch": (s.raw or {}).get("git_branch"),
         "children": [session_summary(c) for c in s.children],
     }

{scrollback-0.1.2 → scrollback-0.2.0}/src/scrollback/sources/claudecode.py

@@ -228,6 +228,7 @@ class ClaudeCodeSource(Source):
                 message_count=meta["msg_count"],
                 children=children,
                 raw={"path": str(f), "git_branch": meta["git_branch"]},
+                **_usage_from_meta(meta),
             )
 
     def _subagent_summary(self, parent_path: Path, sub_path: Path) -> Session:
@@ -252,6 +253,7 @@ class ClaudeCodeSource(Source):
             parent_id=parent_id,
             message_count=(sm or {}).get("msg_count", 0),
             raw={"path": str(sub_path)},
+            **_usage_from_meta(sm or {}),
         )
 
     # -- single session -----------------------------------------------------
@@ -338,6 +340,7 @@ class ClaudeCodeSource(Source):
             message_count=meta["msg_count"],
             messages=(),
             raw={"path": str(path), "git_branch": meta["git_branch"]},
+            **_usage_from_meta(meta),
         )
 
     def load_messages(
@@ -411,6 +414,10 @@ def _scan_metadata(path: Path) -> dict[str, Any] | None:
     first_user_text: str | None = None
     msg_count = 0
     seen = False
+    # Usage accumulators. Claude Code records per-turn `usage` on assistant
+    # messages; summing across turns matches the agent's own session totals.
+    tok_in = tok_out = tok_cache_read = tok_cache_write = 0
+    any_usage = False
 
     for obj in _iter_lines(path):
         seen = True
@@ -439,6 +446,14 @@ def _scan_metadata(path: Path) -> dict[str, Any] | None:
                 mv = m.get("model")
                 if mv and mv != "<synthetic>":
                     model = mv
+            if isinstance(m, dict):
+                u = m.get("usage")
+                if isinstance(u, dict):
+                    any_usage = True
+                    tok_in += _int(u.get("input_tokens"))
+                    tok_out += _int(u.get("output_tokens"))
+                    tok_cache_read += _int(u.get("cache_read_input_tokens"))
+                    tok_cache_write += _int(u.get("cache_creation_input_tokens"))
             if (
                 first_user_text is None
                 and t == "user"
@@ -458,6 +473,27 @@ def _scan_metadata(path: Path) -> dict[str, Any] | None:
         "first_ts": first_ts,
         "last_ts": last_ts,
         "msg_count": msg_count,
+        # Only report usage when the transcript actually carried any, so
+        # sessions with no usage records stay None (not a misleading 0).
+        "tokens_input": tok_in if any_usage else None,
+        "tokens_output": tok_out if any_usage else None,
+        "tokens_cache_read": tok_cache_read if any_usage else None,
+        "tokens_cache_write": tok_cache_write if any_usage else None,
+    }
+
+
+def _int(v: Any) -> int:
+    """Coerce a usage value to int, treating missing/garbage as 0."""
+    return v if isinstance(v, int) else 0
+
+
+def _usage_from_meta(meta: dict[str, Any]) -> dict[str, Any]:
+    """Pull the usage fields out of a scan-metadata dict (all may be None)."""
+    return {
+        "tokens_input": meta.get("tokens_input"),
+        "tokens_output": meta.get("tokens_output"),
+        "tokens_cache_read": meta.get("tokens_cache_read"),
+        "tokens_cache_write": meta.get("tokens_cache_write"),
     }
 
 
@@ -560,6 +596,7 @@ def _parse_session(
         message_count=len(messages),
         messages=tuple(messages),
         raw={"path": str(path), "git_branch": meta["git_branch"]},
+        **_usage_from_meta(meta),
     )
 
 

{scrollback-0.1.2 → scrollback-0.2.0}/src/scrollback/sources/codex.py

@@ -118,6 +118,7 @@ class CodexSource(Source):
                 model=meta["model"],
                 message_count=meta["msg_count"],
                 raw={"path": str(f)},
+                **_usage_from_meta(meta),
             )
 
     # -- single session -----------------------------------------------------
@@ -141,12 +142,23 @@ class CodexSource(Source):
             message_count=len(messages),
             messages=tuple(messages),
             raw={"path": str(path)},
+            **_usage_from_meta(meta),
         )
 
 
 # -- parsing helpers -------------------------------------------------------
 
 
+def _usage_from_meta(meta: dict[str, Any]) -> dict[str, Any]:
+    """Pull usage fields out of a scan-metadata dict (all may be None)."""
+    return {
+        "tokens_input": meta.get("tokens_input"),
+        "tokens_output": meta.get("tokens_output"),
+        "tokens_cache_read": meta.get("tokens_cache_read"),
+        "tokens_cache_write": meta.get("tokens_cache_write"),
+    }
+
+
 def _iter_lines(path: Path) -> Iterator[dict[str, Any]]:
     try:
         with path.open("r", encoding="utf-8", errors="replace") as fh:
@@ -198,6 +210,7 @@ def _scan_meta(path: Path) -> dict[str, Any] | None:
     last_ts: str | int | None = None
     msg_count = 0
     seen = False
+    usage: dict[str, int] | None = None
 
     for obj in _iter_lines(path):
         seen = True
@@ -219,6 +232,12 @@ def _scan_meta(path: Path) -> dict[str, Any] | None:
                 txt = _record_text(p).strip()
                 if txt and not txt.startswith("<"):
                     title = " ".join(txt.split())[:60]
+        # Best-effort usage: Codex emits token counts on some record types
+        # (e.g. a `token_count` event). Take the LAST cumulative reading we
+        # see. Absent in older/other formats -> usage stays None.
+        latest = _token_usage(obj, p)
+        if latest is not None:
+            usage = latest
 
     if not seen:
         return None
@@ -231,6 +250,52 @@ def _scan_meta(path: Path) -> dict[str, Any] | None:
         "first_ts": first_ts,
         "last_ts": last_ts,
         "msg_count": msg_count,
+        "tokens_input": (usage or {}).get("input"),
+        "tokens_output": (usage or {}).get("output"),
+        "tokens_cache_read": (usage or {}).get("cache_read"),
+        "tokens_cache_write": (usage or {}).get("cache_write"),
+    }
+
+
+def _token_usage(obj: dict[str, Any], payload: dict[str, Any]) -> dict[str, int] | None:
+    """Best-effort extraction of a token-usage reading from a Codex record.
+
+    Codex's rollout format has changed across versions; this looks for a
+    `token_count` / `usage` object in a few known shapes and returns a
+    normalized {input, output, cache_read, cache_write} dict, or None. It is
+    intentionally forgiving: unknown shapes yield None rather than raising.
+    """
+    src = None
+    # A record whose own type is token_count/usage carries the fields inline.
+    if payload.get("type") in ("token_count", "usage"):
+        src = payload
+    else:
+        for cand in (payload.get("token_count"), payload.get("usage"),
+                     obj.get("token_count"), obj.get("usage")):
+            if isinstance(cand, dict):
+                src = cand
+                break
+    if src is None:
+        return None
+    # Some versions nest the counts under an "info"/"total"/"last" object.
+    for nest in ("info", "total", "last"):
+        if isinstance(src.get(nest), dict):
+            src = src[nest]
+            break
+
+    def g(*keys: str) -> int:
+        for k in keys:
+            v = src.get(k)
+            if isinstance(v, int):
+                return v
+        return 0
+
+    read = g("cached_input_tokens", "cache_read_input_tokens", "cache_read")
+    return {
+        "input": g("input_tokens", "input", "prompt_tokens"),
+        "output": g("output_tokens", "output", "completion_tokens"),
+        "cache_read": read,
+        "cache_write": g("cache_creation_input_tokens", "cache_write"),
     }
 
 

{scrollback-0.1.2 → scrollback-0.2.0}/src/scrollback/sources/opencode.py

@@ -80,12 +80,13 @@ class OpenCodeSource(Source):
         return self._list_sessions()
 
     def _list_sessions(self) -> Iterator[Session]:
+        # `SELECT s.*` + `_col` keeps us tolerant of schema drift: newer usage
+        # columns (cache/reasoning) are read when present and default to None
+        # on older opencode databases that lack them.
         with self._connect() as conn:
             rows = conn.execute(
                 """
-                SELECT s.id, s.title, s.directory, s.time_created,
-                       s.time_updated, s.model, s.agent, s.parent_id,
-                       s.cost, s.tokens_input, s.tokens_output,
+                SELECT s.*,
                        (SELECT COUNT(*) FROM message m WHERE m.session_id = s.id)
                            AS msg_count
                 FROM session s
@@ -104,9 +105,7 @@ class OpenCodeSource(Source):
                 agent=r["agent"],
                 parent_id=r["parent_id"],
                 message_count=r["msg_count"],
-                cost=r["cost"],
-                tokens_input=r["tokens_input"],
-                tokens_output=r["tokens_output"],
+                **_usage_from_row(r),
             )
 
     # -- single session -----------------------------------------------------
@@ -175,10 +174,8 @@ class OpenCodeSource(Source):
             agent=srow["agent"],
             parent_id=srow["parent_id"],
             message_count=message_count,
-            cost=_col(srow, "cost"),
-            tokens_input=_col(srow, "tokens_input"),
-            tokens_output=_col(srow, "tokens_output"),
             messages=messages,
+            **_usage_from_row(srow),
         )
 
     # -- windowed loading ---------------------------------------------------
@@ -271,6 +268,18 @@ def _col(row: sqlite3.Row, key: str) -> Any:
         return None
 
 
+def _usage_from_row(row: sqlite3.Row) -> dict[str, Any]:
+    """Extract the usage fields from a session row (missing columns -> None)."""
+    return {
+        "cost": _col(row, "cost"),
+        "tokens_input": _col(row, "tokens_input"),
+        "tokens_output": _col(row, "tokens_output"),
+        "tokens_cache_read": _col(row, "tokens_cache_read"),
+        "tokens_cache_write": _col(row, "tokens_cache_write"),
+        "tokens_reasoning": _col(row, "tokens_reasoning"),
+    }
+
+
 def _loads(s: str | None) -> dict[str, Any]:
     if not s:
         return {}

{scrollback-0.1.2 → scrollback-0.2.0}/src/scrollback/store.py

@@ -40,6 +40,9 @@ class Stats:
     total_messages: int
     total_tokens_input: int
     total_tokens_output: int
+    total_tokens_cache_read: int
+    total_tokens_cache_write: int
+    total_tokens_reasoning: int
     total_cost: float
     oldest: datetime | None
     newest: datetime | None
@@ -82,6 +85,9 @@ class Store:
         total_messages = 0
         total_tokens_in = 0
         total_tokens_out = 0
+        total_cache_read = 0
+        total_cache_write = 0
+        total_reasoning = 0
         total_cost = 0.0
         oldest: datetime | None = None
         newest: datetime | None = None
@@ -98,6 +104,12 @@ class Store:
                 total_tokens_in += s.tokens_input
             if s.tokens_output:
                 total_tokens_out += s.tokens_output
+            if s.tokens_cache_read:
+                total_cache_read += s.tokens_cache_read
+            if s.tokens_cache_write:
+                total_cache_write += s.tokens_cache_write
+            if s.tokens_reasoning:
+                total_reasoning += s.tokens_reasoning
             if s.cost:
                 total_cost += s.cost
             when = s.updated or s.created
@@ -112,6 +124,9 @@ class Store:
             total_messages=total_messages,
             total_tokens_input=total_tokens_in,
             total_tokens_output=total_tokens_out,
+            total_tokens_cache_read=total_cache_read,
+            total_tokens_cache_write=total_cache_write,
+            total_tokens_reasoning=total_reasoning,
             total_cost=total_cost,
             oldest=oldest,
             newest=newest,

{scrollback-0.1.2 → scrollback-0.2.0}/src/scrollback/web/static/app.js

@@ -690,7 +690,9 @@ function renderHeader(meta) {
       copyId,
       meta.model ? el("span", {}, "model: " + meta.model) : null,
       meta.git_branch ? el("span", {}, "branch: " + meta.git_branch) : null,
-      meta.tokens_input != null ? el("span", {}, `tokens ${fmtTokens(meta.tokens_input)}/${fmtTokens(meta.tokens_output)}`) : null,
+      meta.tokens_input != null ? el("span", { title: "input / output tokens" }, `tokens ${fmtTokens(meta.tokens_input)}/${fmtTokens(meta.tokens_output)}`) : null,
+      meta.tokens_cache_read != null && (meta.tokens_cache_read || meta.tokens_cache_write)
+        ? el("span", { title: "prompt cache read / write" }, `cache ${fmtTokens(meta.tokens_cache_read)}/${fmtTokens(meta.tokens_cache_write)}`) : null,
       el("span", {}, fmtDate(meta.created)),
       el("span", {}, `${meta.message_count} messages`),
       meta.directory ? el("span", {}, meta.directory) : null

{scrollback-0.1.2 → scrollback-0.2.0}/tests/test_stats_resume.py

@@ -59,6 +59,10 @@ def test_stats_aggregates():
     assert st.total_messages == 22
     assert st.total_tokens_input == 220
     assert st.total_tokens_output == 37
+    # These sessions carry no cache/reasoning usage, so the new totals are 0.
+    assert st.total_tokens_cache_read == 0
+    assert st.total_tokens_cache_write == 0
+    assert st.total_tokens_reasoning == 0
     assert abs(st.total_cost - 0.75) < 1e-9
     assert st.oldest.day == 1 and st.newest.day == 5
 

scrollback-0.2.0/tests/test_usage.py

@@ -0,0 +1,266 @@
+"""Usage/token accounting across adapters, stats, and export.
+
+Covers the input/output/cache-read/cache-write/reasoning fields end to end:
+each adapter parses what its format exposes, sessions with no usage stay
+None (not a misleading 0), Store.stats() sums them, and the export/summary
+surfaces render them.
+"""
+
+import json
+import sqlite3
+from pathlib import Path
+
+from scrollback import export
+from scrollback.models import Message, Part, Session
+from scrollback.sources.claudecode import ClaudeCodeSource
+from scrollback.sources.codex import CodexSource
+from scrollback.sources.opencode import OpenCodeSource
+from scrollback.store import Store
+
+
+# -- opencode (SQLite columns) --------------------------------------------
+
+def _make_opencode_db(path: Path, *, with_cache_cols: bool) -> None:
+    conn = sqlite3.connect(path)
+    cache_cols = (
+        ", tokens_cache_read INTEGER, tokens_cache_write INTEGER, "
+        "tokens_reasoning INTEGER"
+        if with_cache_cols else ""
+    )
+    conn.executescript(
+        f"""
+        CREATE TABLE session (
+            id TEXT PRIMARY KEY, project_id TEXT, parent_id TEXT,
+            directory TEXT, title TEXT, time_created INTEGER,
+            time_updated INTEGER, agent TEXT, model TEXT,
+            cost REAL, tokens_input INTEGER, tokens_output INTEGER{cache_cols}
+        );
+        CREATE TABLE message (id TEXT PRIMARY KEY, session_id TEXT,
+            time_created INTEGER, data TEXT);
+        CREATE TABLE part (id TEXT PRIMARY KEY, message_id TEXT,
+            session_id TEXT, time_created INTEGER, data TEXT);
+        """
+    )
+    if with_cache_cols:
+        conn.execute(
+            "INSERT INTO session (id, title, time_created, time_updated, cost, "
+            "tokens_input, tokens_output, tokens_cache_read, tokens_cache_write, "
+            "tokens_reasoning) VALUES (?,?,?,?,?,?,?,?,?,?)",
+            ("s1", "Heat eqn", 1000, 2000, 0.42, 1500, 3000, 250000, 40000, 800),
+        )
+    else:
+        conn.execute(
+            "INSERT INTO session (id, title, time_created, time_updated, cost, "
+            "tokens_input, tokens_output) VALUES (?,?,?,?,?,?,?)",
+            ("s1", "Heat eqn", 1000, 2000, 0.42, 1500, 3000),
+        )
+    conn.commit()
+    conn.close()
+
+
+def test_opencode_reads_cache_columns(tmp_path):
+    db = tmp_path / "opencode.db"
+    _make_opencode_db(db, with_cache_cols=True)
+    src = OpenCodeSource(db_path=db)
+
+    listed = next(iter(src.list_sessions()))
+    assert listed.tokens_input == 1500
+    assert listed.tokens_output == 3000
+    assert listed.tokens_cache_read == 250000
+    assert listed.tokens_cache_write == 40000
+    assert listed.tokens_reasoning == 800
+
+    full = src.load_session("s1")
+    assert full.tokens_cache_read == 250000
+    assert full.tokens_cache_write == 40000
+
+
+def test_opencode_tolerates_db_without_cache_columns(tmp_path):
+    # Older opencode DBs lack the cache columns; the adapter must not crash and
+    # should report them as None.
+    db = tmp_path / "opencode.db"
+    _make_opencode_db(db, with_cache_cols=False)
+    src = OpenCodeSource(db_path=db)
+
+    listed = next(iter(src.list_sessions()))
+    assert listed.tokens_input == 1500
+    assert listed.tokens_cache_read is None
+    assert listed.tokens_cache_write is None
+    assert listed.tokens_reasoning is None
+
+
+# -- Claude Code (per-turn usage in JSONL) --------------------------------
+
+def _cc_assistant(text, ts, sid, usage=None):
+    msg = {"role": "assistant", "model": "claude-x",
+           "content": [{"type": "text", "text": text}]}
+    if usage is not None:
+        msg["usage"] = usage
+    return {"type": "assistant", "timestamp": ts, "sessionId": sid, "message": msg}
+
+
+def _cc_user(text, ts, sid):
+    return {"type": "user", "timestamp": ts, "sessionId": sid, "cwd": "/proj",
+            "message": {"role": "user", "content": text}}
+
+
+def test_claudecode_sums_per_turn_usage(tmp_path):
+    root = tmp_path / "projects"   # adapter root is the `projects/` dir
+    sid = "aaaaaaaa-1111-2222-3333-444444444444"
+    f = root / "-proj" / f"{sid}.jsonl"
+    f.parent.mkdir(parents=True)
+    rows = [
+        _cc_user("q1", "2026-03-14T09:30:00Z", sid),
+        _cc_assistant("a1", "2026-03-14T09:30:05Z", sid, usage={
+            "input_tokens": 100, "output_tokens": 200,
+            "cache_read_input_tokens": 5000, "cache_creation_input_tokens": 300,
+        }),
+        _cc_user("q2", "2026-03-14T09:31:00Z", sid),
+        _cc_assistant("a2", "2026-03-14T09:31:05Z", sid, usage={
+            "input_tokens": 50, "output_tokens": 400,
+            "cache_read_input_tokens": 8000, "cache_creation_input_tokens": 100,
+        }),
+    ]
+    with f.open("w") as fh:
+        for r in rows:
+            fh.write(json.dumps(r) + "\n")
+
+    src = ClaudeCodeSource(root=root)
+    s = next(iter(src.list_sessions()))
+    assert s.tokens_input == 150       # 100 + 50
+    assert s.tokens_output == 600      # 200 + 400
+    assert s.tokens_cache_read == 13000  # 5000 + 8000
+    assert s.tokens_cache_write == 400   # 300 + 100
+
+    # load_session path agrees with the listing path.
+    full = src.load_session(s.id)
+    assert full.tokens_cache_read == 13000
+
+
+def test_claudecode_usage_none_when_absent(tmp_path):
+    root = tmp_path / "projects"
+    sid = "bbbbbbbb-1111-2222-3333-444444444444"
+    f = root / "-proj" / f"{sid}.jsonl"
+    f.parent.mkdir(parents=True)
+    with f.open("w") as fh:
+        fh.write(json.dumps(_cc_user("hi", "2026-03-14T09:30:00Z", sid)) + "\n")
+        fh.write(json.dumps(_cc_assistant("yo", "2026-03-14T09:30:05Z", sid)) + "\n")
+
+    s = next(iter(ClaudeCodeSource(root=root).list_sessions()))
+    assert s.tokens_input is None
+    assert s.tokens_cache_read is None
+
+
+# -- Codex (best-effort; None when the format carries no usage) ------------
+
+def _codex_rollout(tmp_path: Path, rows: list[dict]) -> Path:
+    d = tmp_path / "sessions" / "2025" / "01" / "31"
+    d.mkdir(parents=True)
+    f = d / "rollout-2025-01-31T12-34-56-abcd1234-ef56-7890-abcd-ef1234567890.jsonl"
+    f.write_text("\n".join(json.dumps(r) for r in rows) + "\n")
+    return f
+
+
+def test_codex_usage_none_without_token_records(tmp_path):
+    _codex_rollout(tmp_path, [
+        {"type": "session_meta", "timestamp": "2025-01-31T12:34:56Z",
+         "cwd": "/proj", "model": "gpt-5-codex"},
+        {"type": "response_item", "timestamp": "2025-01-31T12:35:00Z",
+         "payload": {"type": "message", "role": "user",
+                     "content": [{"type": "input_text", "text": "hi"}]}},
+    ])
+    s = next(iter(CodexSource(root=tmp_path / "sessions").list_sessions()))
+    assert s.tokens_input is None
+    assert s.tokens_cache_read is None
+
+
+def test_codex_parses_token_count_when_present(tmp_path):
+    _codex_rollout(tmp_path, [
+        {"type": "session_meta", "timestamp": "2025-01-31T12:34:56Z",
+         "cwd": "/proj", "model": "gpt-5-codex"},
+        {"type": "response_item", "timestamp": "2025-01-31T12:35:00Z",
+         "payload": {"type": "message", "role": "user",
+                     "content": [{"type": "input_text", "text": "hi"}]}},
+        {"type": "event_msg", "timestamp": "2025-01-31T12:35:10Z",
+         "payload": {"type": "token_count", "input_tokens": 900,
+                     "output_tokens": 120, "cached_input_tokens": 4000}},
+    ])
+    s = next(iter(CodexSource(root=tmp_path / "sessions").list_sessions()))
+    assert s.tokens_input == 900
+    assert s.tokens_output == 120
+    assert s.tokens_cache_read == 4000
+
+
+# -- stats aggregation -----------------------------------------------------
+
+class _FakeSource:
+    name = "fake"
+    label = "Fake"
+
+    def __init__(self, sessions):
+        self._s = sessions
+
+    def is_available(self):
+        return True
+
+    def location(self):
+        return Path("/tmp/fake")
+
+    def list_sessions(self):
+        return iter(self._s)
+
+    def load_session(self, sid):
+        return next((s for s in self._s if s.id == sid), None)
+
+
+def _sess(sid, **usage):
+    from datetime import datetime, timezone
+    dt = datetime(2026, 3, 14, tzinfo=timezone.utc)
+    return Session(id=sid, source="fake", title=sid, directory=None,
+                   created=dt, updated=dt, message_count=1, **usage)
+
+
+def test_stats_sums_cache_and_reasoning():
+    store = Store([_FakeSource([
+        _sess("a", tokens_input=100, tokens_output=200,
+              tokens_cache_read=1000, tokens_cache_write=50, tokens_reasoning=10),
+        _sess("b", tokens_input=5, tokens_output=7,
+              tokens_cache_read=2000, tokens_cache_write=25, tokens_reasoning=3),
+        _sess("c"),  # no usage -> contributes nothing
+    ])])
+    st = store.stats()
+    assert st.total_tokens_input == 105
+    assert st.total_tokens_output == 207
+    assert st.total_tokens_cache_read == 3000
+    assert st.total_tokens_cache_write == 75
+    assert st.total_tokens_reasoning == 13
+
+
+# -- export surfacing ------------------------------------------------------
+
+def _msg():
+    return Message(id="m", role="assistant", created=None,
+                   parts=(Part(id="p", type="text", text="hi"),))
+
+
+def test_export_usage_summary_in_markdown_and_html():
+    s = Session(id="s", source="opencode", title="t", directory=None,
+                created=None, updated=None, messages=(_msg(),), message_count=1,
+                tokens_input=1500, tokens_output=3000,
+                tokens_cache_read=250000, tokens_cache_write=40000, cost=0.42)
+    md = export.to_markdown(s)
+    assert "**Usage**" in md
+    assert "1.5k in / 3.0k out" in md
+    assert "cache 250.0k read / 40.0k write" in md
+    assert "$0.42" in md
+
+    html = export.to_html(s)
+    assert "usage:" in html
+    assert "250.0k read" in html
+
+
+def test_export_no_usage_line_when_absent():
+    s = Session(id="s", source="aider", title="t", directory=None,
+                created=None, updated=None, messages=(_msg(),), message_count=1)
+    assert "**Usage**" not in export.to_markdown(s)
+    assert "usage:" not in export.to_html(s)