cctx-cli 1.13.0__tar.gz → 1.15.0__tar.gz

{cctx_cli-1.13.0 → cctx_cli-1.15.0}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 <!-- version list -->
 
+## v1.15.0 (2026-06-20)
+
+### Features
+
+- Compaction findings — surface compaction events and re-fetch waste (#93)
+  ([#123](https://github.com/jacquardlabs/cctx/pull/123),
+  [`cdab064`](https://github.com/jacquardlabs/cctx/commit/cdab0640b720e127549af63c22747555bd832b2c))
+
+
+## v1.14.0 (2026-06-20)
+
+### Features
+
+- Savings framing + health grade behind --health flag (#101)
+  ([#122](https://github.com/jacquardlabs/cctx/pull/122),
+  [`ee4bc28`](https://github.com/jacquardlabs/cctx/commit/ee4bc2833d7260275e95666ba45a5952aa174aee))
+
+
 ## v1.13.0 (2026-06-20)
 
 ### Documentation

{cctx_cli-1.13.0 → cctx_cli-1.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.13.0
+Version: 1.15.0
 Summary: Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md
 Author: Jacquard Labs
 License-Expression: MIT

{cctx_cli-1.13.0 → cctx_cli-1.15.0}/cctx/__init__.py

@@ -1,3 +1,3 @@
 """cctx: profile, debug, and optimize Claude Code and Agent SDK sessions."""
 
-__version__ = "1.13.0"
+__version__ = "1.15.0"

{cctx_cli-1.13.0 → cctx_cli-1.15.0}/cctx/cli.py

@@ -346,6 +346,13 @@ def ls(project: Path | None) -> None:
     help="Print one verdict line only when findings exist; nothing if clean. "
          "Designed for SessionEnd hook use (cctx init).",
 )
+@click.option(
+    "--health",
+    "health",
+    is_flag=True,
+    default=False,
+    help="Show health grade (A–F) and per-finding savings estimate.",
+)
 def autopsy(
     target: Path | None,
     since: str | None,
@@ -358,6 +365,7 @@ def autopsy(
     turn_num: int | None,
     json_out: bool,
     quiet: bool,
+    health: bool,
 ) -> None:
     """Diagnose a session or project directory.
 
@@ -488,7 +496,7 @@ def autopsy(
             from cctx.renderers.github import write_github_summary
             write_github_summary(diagnosis)
         else:
-            render_diagnosis(diagnosis, session_path=target)
+            render_diagnosis(diagnosis, session_path=target, show_health=health)
         if fail_on_findings and diagnosis.findings:
             raise SystemExit(1)
 

{cctx_cli-1.13.0 → cctx_cli-1.15.0}/cctx/diagnostician/__init__.py

@@ -16,6 +16,7 @@ from typing import TYPE_CHECKING
 from cctx.diagnostician import inflection
 from cctx.diagnostician.patterns import (
     cache_hygiene,
+    compaction,
     dead_end,
     fan_out,
     retry_loop,
@@ -154,6 +155,7 @@ def run(trace: SessionTrace) -> Diagnosis:
         *dead_end.classify(trace),
         *fan_out.classify(trace),
         *cache_hygiene.classify(trace),
+        *compaction.classify(trace),
     ]
     findings.sort(key=lambda f: f.first_turn)
 

cctx_cli-1.15.0/cctx/diagnostician/patterns/compaction.py

@@ -0,0 +1,114 @@
+"""Compaction-event classifier.
+
+Detects context-window compaction events and surfaces them as first-class
+findings. Also attributes re-fetch waste: files read before compaction that
+are read again after (token cost of the re-read attributed to the compaction).
+
+Exported helpers:
+  is_compaction_turn(turn) — canonical compaction predicate used by
+    stale_context.py and dead_end.py (replaces their local implementations).
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cctx.models import Confidence, Finding, FindingKind, Severity
+
+if TYPE_CHECKING:
+    from cctx.models import SessionTrace, Turn
+
+
+def is_compaction_turn(turn: Turn) -> bool:
+    """True if this turn represents a context-window compaction event."""
+    if turn.role == "system" and "compact" in turn.text.lower():
+        return True
+    return turn.text.startswith("<context_window")
+
+
+def _classify_impl(trace: SessionTrace) -> list[Finding]:
+    compaction_turns = [t for t in trace.turns if is_compaction_turn(t)]
+    if not compaction_turns:
+        return []
+
+    first_compaction_turn = compaction_turns[0].turn_number
+
+    # Build map of files read before first compaction: key → token_count
+    pre_reads: dict[str, int] = {}
+    for turn in trace.turns:
+        if turn.turn_number >= first_compaction_turn:
+            break
+        for tu in turn.tool_uses:
+            if tu.tool_name == "Read":
+                fp = tu.tool_input.get("file_path", "")
+                if not fp:
+                    continue
+                # Find matching tool result to get token count
+                for tr in turn.tool_results:
+                    if tr.tool_use_id == tu.tool_use_id:
+                        toks = (
+                            tr.token_count
+                            if tr.token_count > 0
+                            else len(tr.content.split()) * 4 // 3
+                        )
+                        pre_reads[f"Read:{fp}"] = toks
+
+    # Detect re-fetches after compaction (first occurrence only per file)
+    re_fetches: list[dict] = []
+    for turn in trace.turns:
+        if turn.turn_number <= first_compaction_turn:
+            continue
+        for tu in turn.tool_uses:
+            if tu.tool_name == "Read":
+                fp = tu.tool_input.get("file_path", "")
+                key = f"Read:{fp}"
+                if key in pre_reads:
+                    re_fetches.append({
+                        "tool_name": tu.tool_name,
+                        "path": fp,
+                        "turn": turn.turn_number,
+                        "tokens": pre_reads[key],
+                    })
+                    del pre_reads[key]  # only flag first re-fetch per file
+
+    total_refetch_tokens = sum(r["tokens"] for r in re_fetches)
+    n_compactions = len(compaction_turns)
+    compaction_turn_numbers = [t.turn_number for t in compaction_turns]
+
+    severity = Severity.HIGH if re_fetches else Severity.LOW
+    confidence = Confidence.HIGH
+
+    parts = [
+        f"{n_compactions} compaction event{'s' if n_compactions > 1 else ''} "
+        f"(turn{'s' if n_compactions > 1 else ''} "
+        f"{', '.join(str(n) for n in compaction_turn_numbers)})"
+    ]
+    if re_fetches:
+        n_files = len(re_fetches)
+        parts.append(
+            f"{n_files} file{'s' if n_files > 1 else ''} re-fetched after compaction "
+            f"(~{total_refetch_tokens:,} tokens)"
+        )
+    summary = "; ".join(parts)
+
+    return [Finding(
+        kind=FindingKind.COMPACTION,
+        severity=severity,
+        confidence=confidence,
+        first_turn=compaction_turn_numbers[0],
+        last_turn=compaction_turn_numbers[-1],
+        evidence={
+            "n_compactions": n_compactions,
+            "compaction_turns": compaction_turn_numbers,
+            "re_fetches": re_fetches,
+            "total_refetch_tokens": total_refetch_tokens,
+        },
+        cost_usd=None,
+        summary=summary,
+    )]
+
+
+def classify(trace: SessionTrace) -> list[Finding]:
+    try:
+        return _classify_impl(trace)
+    except Exception:
+        return []

{cctx_cli-1.13.0 → cctx_cli-1.15.0}/cctx/diagnostician/patterns/dead_end.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 import json
 from typing import TYPE_CHECKING
 
+from cctx.diagnostician.patterns.compaction import is_compaction_turn
 from cctx.models import Confidence, Finding, FindingKind, Severity
 
 if TYPE_CHECKING:
@@ -65,7 +66,7 @@ def _classify_impl(trace: SessionTrace) -> list[Finding]:
 
     for turn in trace.turns:
         # Compaction resets state
-        if turn.text.startswith("<context_window"):
+        if is_compaction_turn(turn):
             run_tool = run_key = None
             run_count = 0
             continue

{cctx_cli-1.13.0 → cctx_cli-1.15.0}/cctx/diagnostician/patterns/stale_context.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from cctx.diagnostician.patterns.compaction import is_compaction_turn
 from cctx.models import Confidence, Finding, FindingKind, Severity
 
 if TYPE_CHECKING:
@@ -33,8 +34,9 @@ def _make_3grams(text: str) -> set[tuple[str, ...]]:
     return {tuple(words[i : i + 3]) for i in range(len(words) - 2)}
 
 
+# Backwards-compat alias — external callers that import _is_compaction keep working.
 def _is_compaction(turn: Turn) -> bool:
-    return turn.role == "system" and "compact" in turn.text.lower()
+    return is_compaction_turn(turn)
 
 
 def _classify_impl(trace: SessionTrace) -> list[Finding]:
@@ -60,7 +62,7 @@ def _classify_impl(trace: SessionTrace) -> list[Finding]:
 
     # Find the turn number of any compaction events
     compaction_turns: set[int] = {
-        t.turn_number for t in trace.turns if _is_compaction(t)
+        t.turn_number for t in trace.turns if is_compaction_turn(t)
     }
 
     last_turn_number = max((t.turn_number for t in trace.turns), default=0)

{cctx_cli-1.13.0 → cctx_cli-1.15.0}/cctx/models.py

@@ -175,6 +175,7 @@ class FindingKind(str, Enum):
     FANOUT_WASTE  = "fanout_waste"
     PROJECT_PATTERN = "project_pattern"
     CACHE_HYGIENE = "cache_hygiene"
+    COMPACTION    = "compaction"
 
 
 KIND_LABEL: dict[FindingKind, str] = {
@@ -186,6 +187,7 @@ KIND_LABEL: dict[FindingKind, str] = {
     FindingKind.FANOUT_WASTE:  "FANOUT WASTE",
     FindingKind.PROJECT_PATTERN: "PROJECT PATTERN",
     FindingKind.CACHE_HYGIENE: "CACHE HYGIENE",
+    FindingKind.COMPACTION:    "COMPACTION",
 }
 
 # Maps FindingKind to the exact ## heading emitted by its recommender patch
@@ -200,6 +202,7 @@ MANAGED_HEADINGS: dict[FindingKind, str] = {
     FindingKind.DEAD_END:      "## Exploration discipline",
     FindingKind.FANOUT_WASTE:  "## Fan-out discipline",
     FindingKind.CACHE_HYGIENE: "## Cache hygiene",
+    FindingKind.COMPACTION:    "## Compaction hygiene",
 }
 
 # Project-specific patterns use a heading that embeds tool+key, so the managed

{cctx_cli-1.13.0 → cctx_cli-1.15.0}/cctx/recommender/claude_md.py

@@ -76,6 +76,15 @@ _CACHE_HYGIENE_DIFF = """\
 +with a stable, cacheable preamble. A 10× cost difference separates a warm
 +cache hit from a cold input read."""
 
+_COMPACTION_DIFF = """\
++## Compaction hygiene
++
++If context-window compaction occurs mid-session, assume all previously read files
++are gone from context. Re-read only files you actively need for the next step —
++don't reflexively reload everything. Better: compact earlier by summarizing large
++tool outputs once you've extracted what you need, so compaction doesn't erase
++work-in-progress state."""
+
 _TEMPLATES: dict[FindingKind, tuple[str, str, str]] = {
     # kind → (description, diff_body, target_file)
     FindingKind.RETRY_LOOP:    ("Add retry discipline rule", _RETRY_LOOP_DIFF, "CLAUDE.md"),
@@ -85,6 +94,7 @@ _TEMPLATES: dict[FindingKind, tuple[str, str, str]] = {
     FindingKind.DEAD_END:      ("Add exploration discipline rule", _DEAD_END_DIFF, "CLAUDE.md"),
     FindingKind.FANOUT_WASTE:  ("Add fan-out discipline rule", _FANOUT_WASTE_DIFF, "CLAUDE.md"),
     FindingKind.CACHE_HYGIENE: ("Add cache hygiene rule", _CACHE_HYGIENE_DIFF, "CLAUDE.md"),
+    FindingKind.COMPACTION:    ("Add compaction hygiene rule", _COMPACTION_DIFF, "CLAUDE.md"),
 }
 
 

{cctx_cli-1.13.0 → cctx_cli-1.15.0}/cctx/renderers/terminal.py

@@ -45,11 +45,35 @@ def _wide_console() -> Console:
     return Console(width=200)
 
 
+def compute_health_grade(diagnosis: Diagnosis) -> str:
+    """A–F grade based on waste fraction and finding severity."""
+    if not diagnosis.findings:
+        return "A"
+
+    has_high = any(f.severity == Severity.HIGH for f in diagnosis.findings)
+    waste_frac = (
+        diagnosis.waste_cost_usd / diagnosis.total_cost_usd
+        if diagnosis.total_cost_usd > 0
+        else 0.0
+    )
+
+    if has_high and waste_frac > 0.50:
+        return "F"
+    if has_high or waste_frac > 0.25:
+        return "D"
+    if waste_frac > 0.10:
+        return "C"
+    if diagnosis.findings:
+        return "B"
+    return "A"
+
+
 def render_diagnosis(
     diagnosis: Diagnosis,
     *,
     session_path: Path | None = None,
     console: Console | None = None,
+    show_health: bool = False,
 ) -> None:
     con = console or _default_console()
 
@@ -77,6 +101,15 @@ def render_diagnosis(
         "~85–95% of actual billing; system framing not observable in JSONL", style="dim"
     ))
 
+    if show_health:
+        grade = compute_health_grade(diagnosis)
+        waste_frac = (
+            diagnosis.waste_cost_usd / diagnosis.total_cost_usd * 100
+            if diagnosis.total_cost_usd > 0
+            else 0.0
+        )
+        con.print(f"Health grade: {grade}  (waste {waste_frac:.0f}% of session cost)")
+
     if diagnosis.subagent_costs:
         show_depth = any(a.depth > 1 for a in diagnosis.subagent_costs)
         tbl = Table(show_header=True, header_style="bold", box=None, padding=(0, 1))
@@ -107,6 +140,8 @@ def render_diagnosis(
         badge = Text(f" {label} ", style=style)
         conf_note = f"({finding.confidence.value} confidence)"
         con.print(badge, conf_note, "—", finding.summary)
+        if show_health and finding.cost_usd is not None:
+            con.print(f"  → savings if fixed: ~${finding.cost_usd:.2f}")
 
     # Patches
     if diagnosis.patches:

{cctx_cli-1.13.0 → cctx_cli-1.15.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cctx-cli"
-version = "1.13.0"
+version = "1.15.0"
 description = "Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md"
 readme = "README.md"
 requires-python = ">=3.10"