release: v1.108.132 — receipt surfaces the persistent lifetime savings meter

Author: jgravelle

CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to jcodemunch-mcp are documented here.
 
+## [1.108.132] - 2026-07-16 - receipt surfaces the lifetime savings meter
+
+`receipt` scans local Claude Code transcripts, which are cleared on reinstall,
+so its windowed figure can badly understate a heavy user's real savings. It now
+also reads the persistent per-call meter (`_savings.json` under the index root,
+which survives reinstalls) and reports lifetime tokens saved plus their value at
+the selected model's input rate, alongside the windowed figure.
+
+### Added
+- A "Lifetime savings (jCodeMunch meter)" section in the `receipt` text report
+  and `--export json` output: cumulative tokens saved and their dollar value at
+  the selected model rate. Shown even when the transcript window is empty.
+- `lifetime_meter()` reader (honors `CODE_INDEX_PATH`); returns None when the
+  meter file is absent, unreadable, or empty.
+
+### Changed
+- The empty-window message now explains the window is transcript-scoped and
+  points at the lifetime meter as the durable record.
+
+No INDEX_VERSION bump, no wire-shape change to any MCP tool.
+
 ## [1.108.131] - 2026-07-16 - receipt/org-report --model choices derive from the price table (Fable selectable)
 
 The `receipt` and `org-report` CLI subparsers in `server.py` built their

CLAUDE.md

@@ -1,6 +1,7 @@
 # jcodemunch-mcp — Project Brief
 
 ## Current State
+- **Version:** 1.108.132 — **`receipt` surfaces the persistent lifetime savings meter.** `receipt` scans local Claude transcripts (cleared on reinstall → its windowed figure understates a heavy user; jjg's all-time transcript scan showed only 504 calls / $10.17 while his real cumulative was 34.3B tokens). Now also reads `_savings.json` under the index root (the per-call meter the MCP server writes on every call, survives Claude Code reinstalls) and reports lifetime tokens saved + dollar value at the selected model's INPUT rate, next to the windowed figure (shown even when the transcript window is empty). New `lifetime_meter(root=)` reader (honors CODE_INDEX_PATH; honest-None on absent/unreadable/zero); wired into `render_text` + `render_json` (`--export json` gains a `lifetime` block). Reconciles the "anemic transcript number vs big lifetime number" gap in ONE place — the fix for the Tim-presentation verifiability concern. New `TestLifetimeMeter` (9). NO INDEX_VERSION / wire change. (Related, NOT in the repo: jjg's personal `~/.claude/hooks/gsd-statusline.js` was corrected from `* 25.00` (Opus OUTPUT rate) to `* 5.00` (Opus INPUT) — input-token savings valued at input pricing; $857K→$171K, defensible.)
 - **Version:** 1.108.131 — **`receipt`/`org-report` `--model` choices derive from the price table (Fable now selectable).** v1.108.130 added Fable to `cli/receipt.py`'s `_MODEL_PRICES_USD_PER_MTOK`, but `server.py`'s CLI dispatcher had a DUPLICATE hardcoded `--model` choices list (`{sonnet,opus,haiku}`) that gated `receipt --model fable` before it reached receipt.py's own parser (jjg hit this on the installed editable src — the code was live, the dispatcher wasn't updated). Both the `receipt` and `org-report` subparsers now build `choices=sorted(_MODEL_PRICES_USD_PER_MTOK)` from the single price table (imported locally in `main()`), so any priced model is selectable and the CLI can't drift from the rates. New parametrized end-to-end test in `tests/test_receipt.py` runs the server CLI for every priced model + asserts none rejected. NO INDEX_VERSION / tool-count / wire change.
 - **Version:** 1.108.130 — **`receipt` CLI price table updated to current Anthropic pricing (+ Fable 5).** Anthropic has reduced input pricing across the Opus line since these models launched; the `receipt` model input-price table (`cli/receipt.py` `_MODEL_PRICES_USD_PER_MTOK`) now tracks current published rates (Opus $5 / Sonnet $3 / Haiku $1) and adds **Claude Fable 5 ($10)** as a selectable model + alternate comparison line (both derive from the table). Source comment cites the dated pricing source (anthropic.com/pricing 2026-06-24); `tests/test_receipt.py` pins the table to it (+ a Fable test). `receipt` values measured token savings at the selected model's current rate; the underlying token savings are unchanged. **Does NOT feed the public token-savings counter, which stores tokens and values them at display time.** jcm's own `storage/token_tracker.PRICING` was already at $5. Sibling parity: jdoc v1.97.0 / jdata v1.19.0 update the same constants in their `token_tracker.PRICING` (feeds per-response `_meta.cost_avoided`). NO INDEX_VERSION / tool-count / wire change. **Framing note: this tracks a vendor price REDUCTION (Anthropic cut Opus input pricing since launch) — NOT a correction of an inflated figure. Never describe it as "overstating."**
 - **Version:** 1.108.129 — **Keystone-protected structural compression for `get_ranked_context` (opt-in `compress=True`; clean-room F-15, competitor unnamed in shipped artifacts).** Renovates an entropy/relevance-guided context-selection idea into jcm's read-only/local/model-free idiom: an oversized symbol body is pruned toward a per-item soft cap so MORE relevant symbols fit the same `token_budget`. New `retrieval/entropy_prune.py` — `prune_source(source, max_tokens, count_tokens)` ranks lines by `line_signal` (normalized Shannon token-entropy × length-weight), keeps the highest-signal lines, and ALWAYS keeps `is_keystone` lines (control-flow/return/raise/yield/assert, signatures `def`/`class`/`@`/`func`/etc., operators `!=`/`==`/`->`/`=>`, and NL constraint cues `must`/`only if`/`unless`/`never`/`require`); dropped runs collapse to an honest `… N low-signal line(s) elided …` marker. O(L) — one token-cost measurement per line; `max_tokens` is a SOFT cap (keystone protection + elision markers can exceed it slightly; the outer `_pack_budget` still enforces the hard total). Wired into BOTH the default and `fusion=True` paths via shared `_compressing_get_tokens(base_get_tokens, token_budget, registry)` (constants `_COMPRESS_TARGET_ITEMS=8`/`_COMPRESS_MIN_ITEM_TOKENS=120`) + `_prune_fields()`; pruned items carry `source_pruned`/`source_kept_lines`/`source_elided_lines`/`source_total_lines`/`source_is_pruned_view`. **Default `compress=False` is byte-identical**; param compact-stripped (`_COMPACT_STRIP_PARAMS["get_ranked_context"]`) so `core_compact` unchanged; NO new tool, NO tool-count change, NO INDEX_VERSION bump. Live-index smoke: 1500-tok budget delivered 12 symbols vs 9 default (3 pruned), same total. New `tests/test_v1_108_129.py` (13); ruff clean; ranked-context/negative-evidence/schema-budget/dispatch-parity/server suites green (150). Origin: a clean-room F-15 renovation of an Atelier-family runtime's entropy/perplexity context-compression stage (competitor unnamed in shipped artifacts, [[feedback_no_competitor_names_in_shipped_artifacts]]; intel kept in session memory); the versus.php warn-box conceded their selection stage was ahead — this closes it.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jcodemunch-mcp"
-version = "1.108.131"
+version = "1.108.132"
 description = "Token-efficient MCP server for source code exploration via tree-sitter AST parsing"
 readme = "README.md"
 requires-python = ">=3.10"

src/jcodemunch_mcp/cli/receipt.py

@@ -19,6 +19,7 @@
 import datetime as _dt
 import io
 import json
+import os
 import sys
 from pathlib import Path
 from typing import Iterable, Optional
@@ -121,6 +122,33 @@ def _projects_root() -> Path:
     return Path.home() / ".claude" / "projects"
 
 
+def _index_root() -> Path:
+    """Index storage root (honors CODE_INDEX_PATH, default ~/.code-index)."""
+    env = os.environ.get("CODE_INDEX_PATH")
+    return Path(env) if env else Path.home() / ".code-index"
+
+
+def lifetime_meter(root: Optional[Path] = None) -> Optional[dict]:
+    """Read the persistent per-call savings meter (``_savings.json``).
+
+    This is the cumulative token savings the MCP server records on *every*
+    tool call, stored under the index root. It survives Claude Code
+    reinstalls (it does not live with the transcripts), so it reflects true
+    lifetime usage even when the local transcript history the window ledger
+    scans has been cleared. Byte-approximate estimate, like the community
+    meter it feeds. Returns None when absent/unreadable/empty.
+    """
+    path = (root or _index_root()) / "_savings.json"
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    total = data.get("total_tokens_saved")
+    if not isinstance(total, (int, float)) or total <= 0:
+        return None
+    return {"total_tokens_saved": int(total), "anon_id": data.get("anon_id")}
+
+
 def _result_byte_length(content) -> int:
     """Return the byte length of a tool_result `content` field.
 
@@ -286,7 +314,29 @@ def dollar_savings(savings_tokens: int, model: str) -> float:
     return (savings_tokens / 1_000_000.0) * rate
 
 
-def render_text(agg: dict, *, days: int, model: str, primary_only: bool = False) -> str:
+def _write_lifetime(out: "io.StringIO", meter: dict, model: str) -> None:
+    """Render the persistent lifetime-meter section."""
+    total = meter["total_tokens_saved"]
+    rate = _MODEL_PRICES_USD_PER_MTOK.get(
+        model.lower(), _MODEL_PRICES_USD_PER_MTOK[_DEFAULT_MODEL]
+    )
+    usd = dollar_savings(total, model)
+    out.write("  Lifetime savings (jCodeMunch meter, all-time):\n")
+    out.write(f"    Tokens saved:                {total:>15,}\n")
+    out.write(f"    Value at {model.title()} pricing (${rate:.2f}/MTok input):  ${usd:,.2f}\n")
+    out.write("    Persistent per-call meter under the index root; survives\n")
+    out.write("    Claude Code reinstalls. The windowed figure above only counts\n")
+    out.write("    tool calls still present in local transcripts.\n\n")
+
+
+def render_text(
+    agg: dict,
+    *,
+    days: int,
+    model: str,
+    primary_only: bool = False,
+    meter: Optional[dict] = None,
+) -> str:
     """Human-readable ledger output."""
     out = io.StringIO()
     totals = agg["totals"]
@@ -295,9 +345,13 @@ def render_text(agg: dict, *, days: int, model: str, primary_only: bool = False)
     out.write("=" * 56 + "\n\n")
 
     if totals["calls"] == 0:
-        out.write("No jcodemunch tool calls found in ~/.claude/projects/.\n")
-        out.write("If you've been using jcodemunch, check that Claude Code is\n")
-        out.write("writing transcripts to that directory (default behaviour).\n")
+        out.write("No jcodemunch tool calls found in the scanned transcript\n")
+        out.write("window (~/.claude/projects/). Local transcripts are cleared on\n")
+        out.write("reinstall; the lifetime meter below is the durable record.\n\n")
+        if meter:
+            _write_lifetime(out, meter, model)
+        else:
+            out.write("No lifetime meter data yet (index root _savings.json).\n")
         return out.getvalue()
 
     out.write(f"  Tool calls:                    {totals['calls']:>12,}\n")
@@ -319,6 +373,9 @@ def render_text(agg: dict, *, days: int, model: str, primary_only: bool = False)
             out.write(f"     ... at {other.title()} pricing (${other_rate:.2f}/MTok):                 ${other_dollars:,.2f}\n")
     out.write("\n")
 
+    if meter:
+        _write_lifetime(out, meter, model)
+
     if per_tool:
         out.write("  Top tools by savings:\n")
         ranked = sorted(
@@ -372,13 +429,18 @@ def render_csv(agg: dict) -> str:
     return out.getvalue()
 
 
-def render_json(agg: dict, *, model: str) -> str:
+def render_json(agg: dict, *, model: str, meter: Optional[dict] = None) -> str:
     payload = {
         "totals": agg["totals"],
         "per_tool": agg["per_tool"],
         "model": model,
         "savings_usd": dollar_savings(agg["totals"]["savings_tokens"], model),
     }
+    if meter:
+        payload["lifetime"] = {
+            "tokens_saved": meter["total_tokens_saved"],
+            "usd": dollar_savings(meter["total_tokens_saved"], model),
+        }
     return json.dumps(payload, indent=2)
 
 
@@ -426,12 +488,13 @@ def main(argv: Optional[list[str]] = None) -> int:
         since = _dt.datetime.now(_dt.timezone.utc) - _dt.timedelta(days=args.days)
 
     agg = aggregate(iter_calls(root, since=since))
+    meter = lifetime_meter()
 
     if args.export:
         target = Path(args.export)
         ext = target.suffix.lower()
         if ext == ".json":
-            target.write_text(render_json(agg, model=args.model), encoding="utf-8")
+            target.write_text(render_json(agg, model=args.model, meter=meter), encoding="utf-8")
         elif ext == ".csv":
             target.write_text(render_csv(agg), encoding="utf-8")
         else:
@@ -443,7 +506,7 @@ def main(argv: Optional[list[str]] = None) -> int:
         print(f"wrote {target}")
         return 0
 
-    sys.stdout.write(render_text(agg, days=args.days, model=args.model))
+    sys.stdout.write(render_text(agg, days=args.days, model=args.model, meter=meter))
     return 0
 
 

tests/test_receipt.py

@@ -17,6 +17,7 @@
     aggregate,
     dollar_savings,
     iter_calls,
+    lifetime_meter,
     render_csv,
     render_explain,
     render_json,
@@ -271,6 +272,62 @@ def test_haiku_cheaper_than_sonnet(self):
         assert _MODEL_PRICES_USD_PER_MTOK["haiku"] < _MODEL_PRICES_USD_PER_MTOK["sonnet"]
 
 
+class TestLifetimeMeter:
+    def test_reads_savings_file(self, tmp_path: Path):
+        (tmp_path / "_savings.json").write_text(
+            json.dumps({"total_tokens_saved": 34_317_586_613, "anon_id": "abc"}),
+            encoding="utf-8",
+        )
+        m = lifetime_meter(root=tmp_path)
+        assert m["total_tokens_saved"] == 34_317_586_613
+        assert m["anon_id"] == "abc"
+
+    def test_missing_file_returns_none(self, tmp_path: Path):
+        assert lifetime_meter(root=tmp_path) is None
+
+    def test_zero_returns_none(self, tmp_path: Path):
+        (tmp_path / "_savings.json").write_text('{"total_tokens_saved": 0}', encoding="utf-8")
+        assert lifetime_meter(root=tmp_path) is None
+
+    def test_corrupt_file_returns_none(self, tmp_path: Path):
+        (tmp_path / "_savings.json").write_text("not json", encoding="utf-8")
+        assert lifetime_meter(root=tmp_path) is None
+
+    def _agg(self):
+        return aggregate([
+            {"tool": "search_symbols", "result_tokens": 1000, "timestamp": "", "session_file": "x"},
+        ])
+
+    def test_render_text_includes_lifetime_at_input_rate(self):
+        meter = {"total_tokens_saved": 34_317_586_613, "anon_id": "x"}
+        out = render_text(self._agg(), days=0, model="opus", meter=meter)
+        assert "Lifetime savings" in out
+        assert "34,317,586,613" in out
+        # 34.3B tokens x $5/MTok (Opus INPUT) = $171,587.93 — not the $25 output rate.
+        assert "$171,587.93" in out
+
+    def test_render_text_no_meter_omits_lifetime(self):
+        out = render_text(self._agg(), days=0, model="opus", meter=None)
+        assert "Lifetime savings" not in out
+
+    def test_empty_transcripts_still_surfaces_meter(self):
+        meter = {"total_tokens_saved": 34_317_586_613, "anon_id": "x"}
+        out = render_text(aggregate([]), days=30, model="opus", meter=meter)
+        assert "No jcodemunch tool calls found" in out
+        assert "Lifetime savings" in out
+        assert "34,317,586,613" in out
+
+    def test_render_json_includes_lifetime(self):
+        meter = {"total_tokens_saved": 1_000_000, "anon_id": "x"}
+        payload = json.loads(render_json(self._agg(), model="opus", meter=meter))
+        assert payload["lifetime"]["tokens_saved"] == 1_000_000
+        assert payload["lifetime"]["usd"] == pytest.approx(5.0)
+
+    def test_render_json_no_meter_omits_lifetime(self):
+        payload = json.loads(render_json(self._agg(), model="opus", meter=None))
+        assert "lifetime" not in payload
+
+
 class TestServerReceiptModelChoices:
     """The `receipt`/`org-report` subparsers in server.py must derive their
     --model choices from the price table, not hardcode a subset. Guards the