cctx-cli 1.2.0__tar.gz → 1.3.0__tar.gz

{cctx_cli-1.2.0 → cctx_cli-1.3.0}/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 <!-- version list -->
 
+## v1.3.0 (2026-05-17)
+
+### Bug Fixes
+
+- Drop unused turn_number from result_map in _find_pairs
+  ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+- Restore WHY comment, fix_key != failure_key guard, tighten tuple annotation
+  ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+- Ruff lint failures (E501, F401, E741, I001) ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+### Documentation
+
+- M14 project-pattern-detection implementation plan
+  ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+- M14 project-specific pattern detection design spec
+  ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+- Note why harvest --since skips project_specific.detect()
+  ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+### Features
+
+- Add ProjectPattern model, AggregateReport.project_patterns, FindingKind.PROJECT_PATTERN
+  ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+- Aggregate.run() returns (Diagnosis, SessionTrace) pairs
+  ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+- Generate_from_patterns() — CLAUDE.md patches from ProjectPatterns
+  ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+- M14 project-specific pattern detection ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+- Project_specific.detect() — cross-session failure/fix pattern detector
+  ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+- Render_aggregate() shows project-specific patterns table
+  ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+- Wire project_specific.detect() into autopsy and harvest --since paths
+  ([#86](https://github.com/jacquardlabs/cctx/pull/86),
+  [`cefc438`](https://github.com/jacquardlabs/cctx/commit/cefc438f9ff638ba2abf529663b5e24707f03bbb))
+
+
 ## v1.2.0 (2026-05-17)
 
 ### Features

{cctx_cli-1.2.0 → cctx_cli-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.2.0
+Version: 1.3.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.2.0 → cctx_cli-1.3.0}/cctx/__init__.py

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

{cctx_cli-1.2.0 → cctx_cli-1.3.0}/cctx/cli.py

@@ -20,6 +20,7 @@ import rich_click as click
 
 from cctx import diagnostician
 from cctx.diagnostician import aggregate
+from cctx.diagnostician.patterns import project_specific
 from cctx.discovery import complete_project as _complete_project
 from cctx.models import KIND_LABEL, AggregateReport
 from cctx.parsers.claude_code import parse_session
@@ -358,11 +359,14 @@ def autopsy(
                     f"Invalid --until date '{until_date}'. Expected YYYY-MM-DD."
                 ) from None
             label = f"{label} until {until_date.strip()}"
-        diagnoses = aggregate.run(project_dir, start, end)
+        pairs = aggregate.run(project_dir, start, end)
+        diagnoses = [d for d, _ in pairs]
         ev = evidence_mod.accumulate(diagnoses)
         if top_n is not None:
             ev = dict(sorted(ev.items(), key=lambda x: x[1].session_count, reverse=True)[:top_n])
-        patches = claude_md.generate_from_evidence(ev)
+        patterns = project_specific.detect(pairs)
+        pattern_patches = claude_md.generate_from_patterns(patterns)
+        patches = claude_md.generate_from_evidence(ev) + pattern_patches
         report = AggregateReport(
             period_label=label,
             sessions_analysed=len(diagnoses),
@@ -371,6 +375,7 @@ def autopsy(
             waste_cost_usd=sum(d.waste_cost_usd for d in diagnoses),
             by_kind=ev,
             patches=patches,
+            project_patterns=patterns,
         )
         render_aggregate(report)
         _aggregate_drilldown(report, diagnoses)
@@ -571,8 +576,11 @@ def harvest(
     if since is not None:
         project_dir = target if target.is_dir() else target.parent
         start, end, _label = parse_since(since)
-        diagnoses = aggregate.run(project_dir, start, end)
+        pairs = aggregate.run(project_dir, start, end)
+        diagnoses = [d for d, _ in pairs]
         ev = evidence_mod.accumulate(diagnoses)
+        # project_specific.detect() intentionally omitted: pattern patches need human review
+        # (autopsy shows them; harvest doesn't auto-apply).
         patches = claude_md.generate_from_evidence(ev)
     else:
         if target.is_dir():

{cctx_cli-1.2.0 → cctx_cli-1.3.0}/cctx/diagnostician/aggregate.py

@@ -1,10 +1,11 @@
 """Cross-session aggregator.
 
-run(project_dir, start, end) -> list[Diagnosis]
+run(project_dir, start, end) -> list[tuple[Diagnosis, SessionTrace]]
 
 Discovers session JSONL files in project_dir modified within [start, end],
-parses each one, runs the per-session diagnostician, and returns the list of
-Diagnoses. The CLI orchestrates the recommender call separately.
+parses each one, runs the per-session diagnostician, and returns
+(Diagnosis, SessionTrace) pairs. The CLI orchestrates recommender and
+project-specific detection separately.
 """
 from __future__ import annotations
 
@@ -17,12 +18,14 @@ from cctx.parsers.claude_code import parse_session
 from cctx.tokenizer import tokenize_session
 
 if TYPE_CHECKING:
-    from cctx.models import Diagnosis
+    from cctx.models import Diagnosis, SessionTrace
 
 UTC = timezone.utc
 
 
-def run(project_dir: Path, start: datetime, end: datetime) -> list[Diagnosis]:
+def run(
+    project_dir: Path, start: datetime, end: datetime
+) -> list[tuple[Diagnosis, SessionTrace]]:
     paths = sorted(project_dir.glob("*.jsonl"), key=lambda p: p.stat().st_mtime)
 
     result = []
@@ -33,7 +36,7 @@ def run(project_dir: Path, start: datetime, end: datetime) -> list[Diagnosis]:
         try:
             trace = tokenize_session(parse_session(path))
             diagnosis = diagnostician.run(trace)
-            result.append(diagnosis)
+            result.append((diagnosis, trace))
         except Exception:
             continue  # skip corrupt sessions; don't fail the whole run
     return result

cctx_cli-1.3.0/cctx/diagnostician/patterns/project_specific.py

@@ -0,0 +1,179 @@
+"""Project-specific pattern detector.
+
+detect(pairs) -> list[ProjectPattern]
+
+Finds (tool_name, failure_key, fix_key) triples that recur in 3+ sessions.
+Bash normalization uses first 3 tokens for cross-session fuzzy matching
+(intentionally looser than retry_loop). No LLM calls.
+"""
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+from cctx.models import ProjectPattern
+from cctx.pricing import price_per_tok
+
+if TYPE_CHECKING:
+    from cctx.models import Diagnosis, SessionTrace, ToolResult
+
+MIN_SESSIONS = 3
+FIX_WINDOW = 10  # turns after last failure to search for the fix
+
+
+def _normalize_key(tool_name: str, tool_input: dict) -> str:
+    match tool_name:
+        case "Bash":
+            tokens = tool_input.get("command", "").strip().split()
+            return " ".join(tokens[:3])
+        case "Edit" | "Read" | "Write":
+            return tool_input.get("file_path", "")
+        case "Grep" | "Glob":
+            return tool_input.get("pattern", "")
+        case _:
+            return json.dumps(tool_input, sort_keys=True)
+
+
+def _is_error(result: ToolResult) -> bool:
+    if result.is_error:
+        return True
+    c = result.content
+    return c.startswith("Error:") or c.startswith("error:") or c.startswith("FAILED")
+
+
+def _find_pairs(trace: SessionTrace) -> list[dict]:
+    """Find failure/fix pairs within one session."""
+    result_map: dict[str, ToolResult] = {}
+    for turn in trace.turns:
+        for tr in turn.tool_results:
+            result_map[tr.tool_use_id] = tr
+
+    records = []
+    for turn in trace.turns:
+        if turn.role != "assistant":
+            continue
+        for tu in turn.tool_uses:
+            result = result_map.get(tu.tool_use_id)
+            if result is None:
+                continue
+            key = _normalize_key(tu.tool_name, tu.tool_input)
+            records.append({
+                "tool_name": tu.tool_name,
+                "key": key,
+                "turn": turn.turn_number,
+                "is_error": _is_error(result),
+            })
+
+    groups: dict[tuple, list] = defaultdict(list)
+    for r in records:
+        groups[(r["tool_name"], r["key"])].append(r)
+
+    found: list[dict] = []
+    seen_pairs: set[tuple] = set()
+
+    for (tool_name, failure_key), group in groups.items():
+        errors = [r for r in group if r["is_error"]]
+        if len(errors) < 2:
+            continue
+
+        first_err_turn = errors[0]["turn"]
+        last_err_turn = errors[-1]["turn"]
+
+        intervening = any(
+            r for r in group
+            if not r["is_error"] and first_err_turn < r["turn"] < last_err_turn
+        )
+        if intervening:
+            continue
+
+        fix = next(
+            (
+                r for r in records
+                if r["tool_name"] == tool_name
+                and not r["is_error"]
+                and r["key"] != failure_key
+                and last_err_turn < r["turn"] <= last_err_turn + FIX_WINDOW
+            ),
+            None,
+        )
+        if fix is None:
+            continue
+
+        pair_key = (tool_name, failure_key, fix["key"])
+        if pair_key in seen_pairs:
+            continue
+        seen_pairs.add(pair_key)
+
+        found.append({
+            "tool_name": tool_name,
+            "failure_key": failure_key,
+            "fix_key": fix["key"],
+            "first_failure_turn": first_err_turn,
+            "fix_turn": fix["turn"],
+        })
+
+    return found
+
+
+def _compute_waste(trace: SessionTrace, first_failure_turn: int, fix_turn: int) -> float:
+    price = price_per_tok(trace.primary_model)
+    total = 0.0
+    for turn in trace.turns:
+        if (
+            turn.role == "assistant"
+            and first_failure_turn <= turn.turn_number <= fix_turn
+            and turn.usage is not None
+        ):
+            total += turn.usage.input_tokens * price
+    return round(total, 4)
+
+
+def detect(pairs: list[tuple[Diagnosis, SessionTrace]]) -> list[ProjectPattern]:
+    """Detect recurring failure/fix patterns across sessions."""
+    session_records: list[dict] = []
+    for _diagnosis, trace in pairs:
+        for p in _find_pairs(trace):
+            session_records.append({
+                "session_id": trace.session_id,
+                "tool_name": p["tool_name"],
+                "failure_key": p["failure_key"],
+                "fix_key": p["fix_key"],
+                "first_failure_turn": p["first_failure_turn"],
+                "fix_turn": p["fix_turn"],
+                "trace": trace,
+            })
+
+    groups: dict[tuple, list] = defaultdict(list)
+    for r in session_records:
+        groups[(r["tool_name"], r["failure_key"], r["fix_key"])].append(r)
+
+    result: list[ProjectPattern] = []
+    for (tool_name, failure_key, fix_key), records in groups.items():
+        seen: dict[str, dict] = {}
+        for r in records:
+            if r["session_id"] not in seen:
+                seen[r["session_id"]] = r
+
+        if len(seen) < MIN_SESSIONS:
+            continue
+
+        unique = list(seen.values())
+        wasted = [r["fix_turn"] - r["first_failure_turn"] for r in unique]
+        avg_wasted_turns = sum(wasted) / len(wasted)
+        total_waste_usd = sum(
+            _compute_waste(r["trace"], r["first_failure_turn"], r["fix_turn"])
+            for r in unique
+        )
+
+        result.append(ProjectPattern(
+            tool_name=tool_name,
+            failure_key=failure_key,
+            fix_key=fix_key,
+            session_count=len(seen),
+            avg_wasted_turns=round(avg_wasted_turns, 1),
+            total_waste_usd=round(total_waste_usd, 4),
+            example_sessions=sorted(r["session_id"] for r in unique)[:3],
+        ))
+
+    return result

{cctx_cli-1.2.0 → cctx_cli-1.3.0}/cctx/models.py

@@ -9,7 +9,7 @@ cctx.renderers, cctx.exporters, cctx.tokenizer.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
@@ -172,6 +172,7 @@ class FindingKind(str, Enum):
     STALE_CONTEXT = "stale_context"
     TOOL_THRASH   = "tool_thrash"
     DEAD_END      = "dead_end"
+    PROJECT_PATTERN = "project_pattern"
 
 
 KIND_LABEL: dict[FindingKind, str] = {
@@ -180,6 +181,7 @@ KIND_LABEL: dict[FindingKind, str] = {
     FindingKind.STALE_CONTEXT: "STALE CONTEXT",
     FindingKind.TOOL_THRASH:   "TOOL THRASH",
     FindingKind.DEAD_END:      "DEAD END",
+    FindingKind.PROJECT_PATTERN: "PROJECT PATTERN",
 }
 
 
@@ -241,6 +243,17 @@ class KindEvidence:
     example_summaries: list[str]
 
 
+@dataclass
+class ProjectPattern:
+    tool_name:         str
+    failure_key:       str
+    fix_key:           str
+    session_count:     int
+    avg_wasted_turns:  float
+    total_waste_usd:   float
+    example_sessions:  list[str]
+
+
 @dataclass
 class AggregateReport:
     period_label:           str  # human-readable, e.g. "last 7 days" or "2026-05-01..2026-05-15"
@@ -250,6 +263,7 @@ class AggregateReport:
     waste_cost_usd:         float
     by_kind:                dict[FindingKind, KindEvidence]
     patches:                list[Patch]
+    project_patterns:       list[ProjectPattern] = field(default_factory=list)
 
 
 # ---------------------------------------------------------------------------

{cctx_cli-1.2.0 → cctx_cli-1.3.0}/cctx/recommender/claude_md.py

@@ -1,7 +1,8 @@
 """Patch generator — turns Findings into copy-pasteable CLAUDE.md diffs.
 
 generate(diagnosis) -> Diagnosis   (single-session path)
-generate_from_evidence(evidence) -> list[Patch]   (cross-session path)
+generate_from_evidence(evidence) -> list[Patch]   (cross-session path, generic findings)
+generate_from_patterns(patterns) -> list[Patch]   (cross-session path, project patterns)
 """
 from __future__ import annotations
 
@@ -11,7 +12,7 @@ from typing import TYPE_CHECKING
 from cctx.models import FindingKind, Patch
 
 if TYPE_CHECKING:
-    from cctx.models import Diagnosis, Finding, KindEvidence
+    from cctx.models import Diagnosis, Finding, KindEvidence, ProjectPattern
 
 # ---------------------------------------------------------------------------
 # Patch templates (append-style unified diffs, v0)
@@ -129,3 +130,25 @@ def generate_from_evidence(
             evidence_summary=example,
         ))
     return patches
+
+
+def generate_from_patterns(patterns: list[ProjectPattern]) -> list[Patch]:
+    """Generate CLAUDE.md patches from cross-session ProjectPatterns."""
+    patches = []
+    for p in patterns:
+        diff = (
+            f"+## Project-specific: {p.tool_name}({p.failure_key})\n"
+            f"+When `{p.failure_key}` fails, use `{p.fix_key}` instead.\n"
+            f"+Re-discovered in {p.session_count} sessions "
+            f"(~${p.total_waste_usd:.2f} wasted)."
+        )
+        patches.append(Patch(
+            target_file="CLAUDE.md",
+            description=f"Project-specific: {p.failure_key} → {p.fix_key}",
+            unified_diff=diff,
+            finding_kind=FindingKind.PROJECT_PATTERN,
+            evidence_summary=(
+                f"Seen in {p.session_count} sessions, ~${p.total_waste_usd:.2f} wasted"
+            ),
+        ))
+    return patches

{cctx_cli-1.2.0 → cctx_cli-1.3.0}/cctx/renderers/terminal.py

@@ -112,22 +112,23 @@ def render_aggregate(report: AggregateReport, *, console: Console | None = None)
         f"Waste: ${report.waste_cost_usd:.2f}"
     )
 
-    if not report.by_kind:
+    if not report.by_kind and not report.project_patterns:
         con.print("\nNo findings across sessions.")
         return
 
     # Summary table
-    table = Table(title="Finding frequency")
-    table.add_column("Pattern")
-    table.add_column("Sessions", justify="right")
-    table.add_column("Waste ($)", justify="right")
-    for kind, ev in report.by_kind.items():
-        table.add_row(
-            _KIND_LABEL.get(kind, kind.value),
-            str(ev.session_count),
-            f"${ev.total_waste_usd:.2f}",
-        )
-    con.print(table)
+    if report.by_kind:
+        table = Table(title="Finding frequency")
+        table.add_column("Pattern")
+        table.add_column("Sessions", justify="right")
+        table.add_column("Waste ($)", justify="right")
+        for kind, ev in report.by_kind.items():
+            table.add_row(
+                _KIND_LABEL.get(kind, kind.value),
+                str(ev.session_count),
+                f"${ev.total_waste_usd:.2f}",
+            )
+        con.print(table)
 
     # Patches
     if report.patches:
@@ -137,6 +138,25 @@ def render_aggregate(report: AggregateReport, *, console: Console | None = None)
             syntax = Syntax(patch.unified_diff, "diff", theme="monokai", word_wrap=True)
             con.print(syntax)
 
+    # Project-specific patterns
+    if report.project_patterns:
+        con.print()
+        pp_table = Table(title="Project-specific patterns")
+        pp_table.add_column("Failure", style="bold")
+        pp_table.add_column("Fix")
+        pp_table.add_column("Sessions", justify="right", style="dim")
+        pp_table.add_column("Avg turns", justify="right", style="dim")
+        pp_table.add_column("Waste", justify="right")
+        for pp in report.project_patterns:
+            pp_table.add_row(
+                pp.failure_key,
+                pp.fix_key,
+                str(pp.session_count),
+                f"{pp.avg_wasted_turns:.1f}",
+                f"~${pp.total_waste_usd:.2f}",
+            )
+        con.print(pp_table)
+
 
 def render_aggregate_drilldown(
     diagnoses: list,