cctx-cli 1.14.0__tar.gz → 1.16.0__tar.gz

{cctx_cli-1.14.0 → cctx_cli-1.16.0}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 <!-- version list -->
 
+## v1.16.0 (2026-06-20)
+
+### Features
+
+- Exploration thrash classifier — detect read-heavy circling without progress (#99)
+  ([#124](https://github.com/jacquardlabs/cctx/pull/124),
+  [`21f3374`](https://github.com/jacquardlabs/cctx/commit/21f3374bb0e2c60db0411213773ad9dffca7ec1f))
+
+
+## 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

{cctx_cli-1.14.0 → cctx_cli-1.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.14.0
+Version: 1.16.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.14.0 → cctx_cli-1.16.0}/cctx/__init__.py

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

{cctx_cli-1.14.0 → cctx_cli-1.16.0}/cctx/diagnostician/__init__.py

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

cctx_cli-1.16.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.14.0 → cctx_cli-1.16.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.16.0/cctx/diagnostician/patterns/exploration_thrash.py

@@ -0,0 +1,192 @@
+"""Exploration-thrash classifier.
+
+Detects when the assistant circles with repeated read/search tool calls
+instead of making progress — high ratio of read-only tools to write/execute
+tools in a window, or repeated identical discovery commands, with no file
+edits or test runs in N consecutive turns.
+
+Signals:
+  1. Sliding window of WINDOW_SIZE consecutive assistant turns where ≥ 80%
+     of tool calls are read-only and no Write/Edit appears.
+  2. Any (tool_name, key) read-only pair called ≥ REPEAT_THRESHOLD times
+     across the full session.
+"""
+from __future__ import annotations
+
+import json
+from collections import Counter
+from typing import TYPE_CHECKING
+
+from cctx.models import Confidence, Finding, FindingKind, Severity
+
+if TYPE_CHECKING:
+    from cctx.models import SessionTrace
+
+WINDOW_SIZE = 6
+READ_RATIO_THRESHOLD = 0.80
+REPEAT_THRESHOLD = 3
+
+_READ_TOOLS = frozenset({"Read", "Grep", "Glob"})
+_WRITE_TOOLS = frozenset({"Write", "Edit", "NotebookEdit"})
+
+_READ_BASH_PREFIXES = (
+    "ls",
+    "find",
+    "cat",
+    "head",
+    "tail",
+    "grep",
+    "rg",
+    "ag",
+    "wc",
+    "file",
+    "stat",
+    "echo",
+    "pwd",
+    "which",
+    "type",
+    "less",
+    "git log",
+    "git diff",
+    "git show",
+    "git status",
+    "git blame",
+)
+
+
+def _is_read_only(tool_name: str, tool_input: dict) -> bool:
+    if tool_name in _READ_TOOLS:
+        return True
+    if tool_name in _WRITE_TOOLS:
+        return False
+    if tool_name == "Bash":
+        cmd = tool_input.get("command", "").lstrip()
+        return any(cmd.startswith(p) for p in _READ_BASH_PREFIXES)
+    return False
+
+
+def _tool_key(tool_name: str, tool_input: dict) -> str:
+    """Canonical key for deduplication."""
+    match tool_name:
+        case "Bash":
+            return tool_input.get("command", "").strip()
+        case "Read" | "Write" | "Edit":
+            return tool_input.get("file_path", "")
+        case "Grep" | "Glob":
+            return tool_input.get("pattern", "")
+        case _:
+            return json.dumps(tool_input, sort_keys=True)
+
+
+def _classify_impl(trace: SessionTrace) -> list[Finding]:
+    # Only look at assistant turns with tool calls
+    active_turns = [
+        t for t in trace.turns
+        if t.role == "assistant" and t.tool_uses
+    ]
+
+    thrash_windows: list[dict] = []
+
+    # Sliding window detection — requires at least WINDOW_SIZE active turns
+    for i in range(max(0, len(active_turns) - WINDOW_SIZE + 1)):
+        window = active_turns[i : i + WINDOW_SIZE]
+        all_calls = [
+            (tu.tool_name, tu.tool_input)
+            for t in window
+            for tu in t.tool_uses
+        ]
+        if not all_calls:
+            continue
+        read_count = sum(
+            1 for name, inp in all_calls if _is_read_only(name, inp)
+        )
+        ratio = read_count / len(all_calls)
+        has_write = any(name in _WRITE_TOOLS for name, _ in all_calls)
+
+        if ratio >= READ_RATIO_THRESHOLD and not has_write:
+            # Avoid double-counting overlapping windows that cover the same turns
+            if (
+                thrash_windows
+                and thrash_windows[-1]["last_turn"] >= window[0].turn_number
+            ):
+                continue
+            thrash_windows.append({
+                "first_turn": window[0].turn_number,
+                "last_turn": window[-1].turn_number,
+                "read_ratio": round(ratio, 2),
+                "total_calls": len(all_calls),
+            })
+
+    # Repeated identical reads
+    read_call_counts: Counter[str] = Counter()
+    read_call_turns: dict[str, list[int]] = {}
+    for turn in trace.turns:
+        if turn.role != "assistant":
+            continue
+        for tu in turn.tool_uses:
+            if _is_read_only(tu.tool_name, tu.tool_input):
+                key = f"{tu.tool_name}:{_tool_key(tu.tool_name, tu.tool_input)}"
+                read_call_counts[key] += 1
+                read_call_turns.setdefault(key, []).append(turn.turn_number)
+
+    repeated_reads: list[dict] = []
+    for key, count in read_call_counts.items():
+        if count >= REPEAT_THRESHOLD:
+            tool_name, _, call_key = key.partition(":")
+            repeated_reads.append({
+                "tool_name": tool_name,
+                "key": call_key[:60],
+                "count": count,
+                "turns": read_call_turns[key],
+            })
+
+    if not thrash_windows and not repeated_reads:
+        return []
+
+    severity = Severity.HIGH if thrash_windows else Severity.MEDIUM
+    confidence = Confidence.MEDIUM
+
+    parts = []
+    if thrash_windows:
+        parts.append(
+            f"{len(thrash_windows)} exploration thrash window"
+            f"{'s' if len(thrash_windows) > 1 else ''} "
+            f"(turns {thrash_windows[0]['first_turn']}–{thrash_windows[-1]['last_turn']}, "
+            f"{thrash_windows[0]['read_ratio']:.0%} read-only)"
+        )
+    if repeated_reads:
+        worst = max(repeated_reads, key=lambda r: r["count"])
+        parts.append(
+            f"{worst['tool_name']}({worst['key']!r}) called {worst['count']}× identically"
+        )
+    summary = "; ".join(parts)
+
+    all_first = min(
+        [w["first_turn"] for w in thrash_windows]
+        + [r["turns"][0] for r in repeated_reads]
+    )
+    all_last = max(
+        [w["last_turn"] for w in thrash_windows]
+        + [r["turns"][-1] for r in repeated_reads]
+    )
+
+    return [Finding(
+        kind=FindingKind.EXPLORATION_THRASH,
+        severity=severity,
+        confidence=confidence,
+        first_turn=all_first,
+        last_turn=all_last,
+        evidence={
+            "thrash_windows": thrash_windows,
+            "repeated_reads": repeated_reads,
+        },
+        cost_usd=None,
+        summary=summary,
+    )]
+
+
+def classify(trace: SessionTrace) -> list[Finding]:
+    try:
+        return _classify_impl(trace)
+    except Exception:
+        return []

{cctx_cli-1.14.0 → cctx_cli-1.16.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.14.0 → cctx_cli-1.16.0}/cctx/models.py

@@ -167,25 +167,29 @@ class SessionTrace:
 
 
 class FindingKind(str, Enum):
-    RETRY_LOOP    = "retry_loop"
-    SCOPE_CREEP   = "scope_creep"
-    STALE_CONTEXT = "stale_context"
-    TOOL_THRASH   = "tool_thrash"
-    DEAD_END      = "dead_end"
-    FANOUT_WASTE  = "fanout_waste"
-    PROJECT_PATTERN = "project_pattern"
-    CACHE_HYGIENE = "cache_hygiene"
+    RETRY_LOOP         = "retry_loop"
+    SCOPE_CREEP        = "scope_creep"
+    STALE_CONTEXT      = "stale_context"
+    TOOL_THRASH        = "tool_thrash"
+    DEAD_END           = "dead_end"
+    FANOUT_WASTE       = "fanout_waste"
+    PROJECT_PATTERN    = "project_pattern"
+    CACHE_HYGIENE      = "cache_hygiene"
+    COMPACTION         = "compaction"
+    EXPLORATION_THRASH = "exploration_thrash"
 
 
 KIND_LABEL: dict[FindingKind, str] = {
-    FindingKind.RETRY_LOOP:    "RETRY LOOP",
-    FindingKind.SCOPE_CREEP:   "SCOPE CREEP",
-    FindingKind.STALE_CONTEXT: "STALE CONTEXT",
-    FindingKind.TOOL_THRASH:   "TOOL THRASH",
-    FindingKind.DEAD_END:      "DEAD END",
-    FindingKind.FANOUT_WASTE:  "FANOUT WASTE",
-    FindingKind.PROJECT_PATTERN: "PROJECT PATTERN",
-    FindingKind.CACHE_HYGIENE: "CACHE HYGIENE",
+    FindingKind.RETRY_LOOP:         "RETRY LOOP",
+    FindingKind.SCOPE_CREEP:        "SCOPE CREEP",
+    FindingKind.STALE_CONTEXT:      "STALE CONTEXT",
+    FindingKind.TOOL_THRASH:        "TOOL THRASH",
+    FindingKind.DEAD_END:           "DEAD END",
+    FindingKind.FANOUT_WASTE:       "FANOUT WASTE",
+    FindingKind.PROJECT_PATTERN:    "PROJECT PATTERN",
+    FindingKind.CACHE_HYGIENE:      "CACHE HYGIENE",
+    FindingKind.COMPACTION:         "COMPACTION",
+    FindingKind.EXPLORATION_THRASH: "EXPLORATION THRASH",
 }
 
 # Maps FindingKind to the exact ## heading emitted by its recommender patch
@@ -193,13 +197,15 @@ KIND_LABEL: dict[FindingKind, str] = {
 # harvest.py imports this (never reaches into recommender/) so emit/sync can
 # identify cctx-managed sections without depending on the patch generator.
 MANAGED_HEADINGS: dict[FindingKind, str] = {
-    FindingKind.RETRY_LOOP:    "## Retry discipline",
-    FindingKind.SCOPE_CREEP:   "## Scope discipline",
-    FindingKind.STALE_CONTEXT: "## Context hygiene",
-    FindingKind.TOOL_THRASH:   "## Tool-call discipline",
-    FindingKind.DEAD_END:      "## Exploration discipline",
-    FindingKind.FANOUT_WASTE:  "## Fan-out discipline",
-    FindingKind.CACHE_HYGIENE: "## Cache hygiene",
+    FindingKind.RETRY_LOOP:         "## Retry discipline",
+    FindingKind.SCOPE_CREEP:        "## Scope discipline",
+    FindingKind.STALE_CONTEXT:      "## Context hygiene",
+    FindingKind.TOOL_THRASH:        "## Tool-call discipline",
+    FindingKind.DEAD_END:           "## Exploration discipline",
+    FindingKind.FANOUT_WASTE:       "## Fan-out discipline",
+    FindingKind.CACHE_HYGIENE:      "## Cache hygiene",
+    FindingKind.COMPACTION:         "## Compaction hygiene",
+    FindingKind.EXPLORATION_THRASH: "## Exploration thrash",
 }
 
 # Project-specific patterns use a heading that embeds tool+key, so the managed

{cctx_cli-1.14.0 → cctx_cli-1.16.0}/cctx/recommender/claude_md.py

@@ -76,15 +76,37 @@ _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."""
+
+_EXPLORATION_THRASH_DIFF = """\
++## Exploration thrash
++
++Before opening another file or running another search, state the specific
++question this call must answer and how the answer changes the next step. If
++you have read 6+ files without writing anything, stop and synthesise what
++you know. Never call the same read or grep more than twice with identical
++arguments — if the first two didn't help, a third won't either."""
+
 _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"),
-    FindingKind.SCOPE_CREEP:   ("Add scope discipline rule", _SCOPE_CREEP_DIFF, "CLAUDE.md"),
+    FindingKind.RETRY_LOOP: ("Add retry discipline rule", _RETRY_LOOP_DIFF, "CLAUDE.md"),
+    FindingKind.SCOPE_CREEP: ("Add scope discipline rule", _SCOPE_CREEP_DIFF, "CLAUDE.md"),
     FindingKind.STALE_CONTEXT: ("Add context hygiene rule", _STALE_CONTEXT_DIFF, "CLAUDE.md"),
-    FindingKind.TOOL_THRASH:   ("Add tool-call discipline rule", _TOOL_THRASH_DIFF, "CLAUDE.md"),
-    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.TOOL_THRASH: ("Add tool-call discipline rule", _TOOL_THRASH_DIFF, "CLAUDE.md"),
+    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"),
+    FindingKind.EXPLORATION_THRASH: (
+        "Add exploration thrash rule", _EXPLORATION_THRASH_DIFF, "CLAUDE.md"
+    ),
 }
 
 

{cctx_cli-1.14.0 → cctx_cli-1.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cctx-cli"
-version = "1.14.0"
+version = "1.16.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"