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

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

@@ -2,6 +2,21 @@
 
 <!-- version list -->
 
+## v1.13.0 (2026-06-20)
+
+### Documentation
+
+- OTEL quickstart for LangGraph + README multi-framework callout
+  ([#119](https://github.com/jacquardlabs/cctx/pull/119),
+  [`98d89d9`](https://github.com/jacquardlabs/cctx/commit/98d89d9fbf882021f0f54eb7f6676ceb3fbc8ca0))
+
+### Features
+
+- KV-cache hygiene diagnosis — hit rate + cause (#96)
+  ([#121](https://github.com/jacquardlabs/cctx/pull/121),
+  [`2a3f49c`](https://github.com/jacquardlabs/cctx/commit/2a3f49cc253d3aacda1cde987138f19518537b89))
+
+
 ## v1.12.1 (2026-06-20)
 
 ### Bug Fixes

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.12.1
+Version: 1.13.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
@@ -20,7 +20,7 @@ Description-Content-Type: text/markdown
 
 # cctx
 
-Diagnose your Claude Code sessions — find out when they went wrong, why they cost what they did, and what to add to your `CLAUDE.md` so it doesn't happen again.
+Diagnose your Claude Code sessions and OpenTelemetry agent traces — find out when they went wrong, why they cost what they did, and what to add to your `CLAUDE.md` so it doesn't happen again.
 
 [![CI](https://github.com/jacquardlabs/cctx/actions/workflows/ci.yml/badge.svg)](https://github.com/jacquardlabs/cctx/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/cctx-cli)](https://pypi.org/project/cctx-cli/)
@@ -53,6 +53,8 @@ cctx watch                # live signals during an active session
 
 cctx is primarily a forensic tool. You reach for it after a session — when something felt off, when the cost was higher than expected, or on a weekly review pass. `cctx watch` runs during a session and surfaces patterns as they happen. It reads the JSONL logs Claude Code writes to `~/.claude/projects/` and produces findings with attributed cost and copy-pasteable `CLAUDE.md` patches.
 
+cctx also diagnoses OTEL traces from the OpenAI Agents SDK, LangGraph, and any framework that emits `gen_ai.*` semantic convention spans — auto-detected, no flags needed. See [Diagnosing other agent frameworks](docs/quickstart-otel.md).
+
 ## Commands
 
 ### `cctx ls` — list projects and sessions
@@ -76,10 +78,15 @@ cctx autopsy ~/Projects/myapp --since 7
 
 # Write a self-contained HTML report
 cctx autopsy ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl --html report.html
+
+# OTEL trace from OpenAI Agents SDK, LangGraph, or any gen_ai.*-instrumented framework
+cctx autopsy agent_trace.jsonl
 ```
 
 Runs three pattern classifiers (retry loop, scope creep, stale context) and prints findings with attributed cost. Use `--since N` to aggregate patterns across multiple sessions in a project.
 
+OTEL traces are auto-detected — cctx sniffs the file format and routes to the right parser. See [docs/quickstart-otel.md](docs/quickstart-otel.md) for how to wire the OTEL exporter in each framework.
+
 ### `cctx harvest` — apply patches to CLAUDE.md
 
 ```bash

{cctx_cli-1.12.1 → cctx_cli-1.13.0}/README.md

@@ -1,6 +1,6 @@
 # cctx
 
-Diagnose your Claude Code sessions — find out when they went wrong, why they cost what they did, and what to add to your `CLAUDE.md` so it doesn't happen again.
+Diagnose your Claude Code sessions and OpenTelemetry agent traces — find out when they went wrong, why they cost what they did, and what to add to your `CLAUDE.md` so it doesn't happen again.
 
 [![CI](https://github.com/jacquardlabs/cctx/actions/workflows/ci.yml/badge.svg)](https://github.com/jacquardlabs/cctx/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/cctx-cli)](https://pypi.org/project/cctx-cli/)
@@ -33,6 +33,8 @@ cctx watch                # live signals during an active session
 
 cctx is primarily a forensic tool. You reach for it after a session — when something felt off, when the cost was higher than expected, or on a weekly review pass. `cctx watch` runs during a session and surfaces patterns as they happen. It reads the JSONL logs Claude Code writes to `~/.claude/projects/` and produces findings with attributed cost and copy-pasteable `CLAUDE.md` patches.
 
+cctx also diagnoses OTEL traces from the OpenAI Agents SDK, LangGraph, and any framework that emits `gen_ai.*` semantic convention spans — auto-detected, no flags needed. See [Diagnosing other agent frameworks](docs/quickstart-otel.md).
+
 ## Commands
 
 ### `cctx ls` — list projects and sessions
@@ -56,10 +58,15 @@ cctx autopsy ~/Projects/myapp --since 7
 
 # Write a self-contained HTML report
 cctx autopsy ~/.claude/projects/-Users-you-Projects-myapp/abc123.jsonl --html report.html
+
+# OTEL trace from OpenAI Agents SDK, LangGraph, or any gen_ai.*-instrumented framework
+cctx autopsy agent_trace.jsonl
 ```
 
 Runs three pattern classifiers (retry loop, scope creep, stale context) and prints findings with attributed cost. Use `--since N` to aggregate patterns across multiple sessions in a project.
 
+OTEL traces are auto-detected — cctx sniffs the file format and routes to the right parser. See [docs/quickstart-otel.md](docs/quickstart-otel.md) for how to wire the OTEL exporter in each framework.
+
 ### `cctx harvest` — apply patches to CLAUDE.md
 
 ```bash

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

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

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

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

cctx_cli-1.13.0/cctx/diagnostician/patterns/cache_hygiene.py

@@ -0,0 +1,125 @@
+"""Cache-hygiene classifier.
+
+Detects sessions with low KV-cache hit rates and identifies the likely cause
+of the miss. A cache miss costs ~10× more than a cache hit on Sonnet
+($3/MTok vs $0.30/MTok), making this one of the highest-value findings.
+
+Thresholds:
+  MIN_TOTAL_TOKENS    = 5_000   — skip tiny sessions
+  HIT_RATE_THRESHOLD  = 0.50   — below this → fire finding
+  HALF_DROP_THRESHOLD = 0.20   — early_rate - late_rate drop to flag as degrading
+"""
+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
+
+MIN_TOTAL_TOKENS = 5_000
+HIT_RATE_THRESHOLD = 0.50
+HALF_DROP_THRESHOLD = 0.20
+
+
+def _hit_rate(turns: list[Turn]) -> float:
+    total_in = sum(
+        t.usage.input_tokens + t.usage.cache_read for t in turns if t.usage
+    )
+    total_cached = sum(t.usage.cache_read for t in turns if t.usage)
+    return total_cached / total_in if total_in > 0 else 0.0
+
+
+def _detect_cause(trace: SessionTrace, assistant_turns: list[Turn]) -> str | None:
+    """Identify the most likely cause of low cache hit rate from JSONL signals."""
+    from cctx.diagnostician.patterns.stale_context import _is_compaction
+
+    # Compaction events invalidate the cache entirely.
+    compaction_turns = [t for t in trace.turns if _is_compaction(t)]
+    if compaction_turns:
+        return (
+            f"context compacted at turn {compaction_turns[0].turn_number}"
+            " (cache invalidated)"
+        )
+
+    # Many tools loaded means the tool-definition prefix is large and unstable.
+    if len(trace.tool_names_loaded) > 20:
+        return (
+            "large tool definition surface (>20 tools loaded)"
+            " reduces prefix stability"
+        )
+
+    # No cached tokens on turn 1 with a non-trivial prompt suggests the
+    # prompt prefix differs each session and cannot be cached.
+    if assistant_turns and assistant_turns[0].usage:
+        first = assistant_turns[0].usage
+        if first.cache_read == 0 and first.input_tokens > 1000:
+            return (
+                "no cached tokens on turn 1"
+                " — prompt prefix may not be stable across sessions"
+            )
+
+    return None
+
+
+def _classify_impl(trace: SessionTrace) -> list[Finding]:
+    assistant_turns = [t for t in trace.turns if t.role == "assistant" and t.usage]
+    if not assistant_turns:
+        return []
+
+    total_tokens = sum(
+        t.usage.input_tokens + t.usage.cache_read for t in assistant_turns
+    )
+    if total_tokens < MIN_TOTAL_TOKENS:
+        return []
+
+    overall_rate = _hit_rate(assistant_turns)
+    if overall_rate >= HIT_RATE_THRESHOLD:
+        return []
+
+    # Split into halves to detect in-session degradation.
+    mid = len(assistant_turns) // 2
+    early_rate = _hit_rate(assistant_turns[:mid]) if mid > 0 else overall_rate
+    late_rate = (
+        _hit_rate(assistant_turns[mid:]) if mid < len(assistant_turns) else overall_rate
+    )
+
+    cause = _detect_cause(trace, assistant_turns)
+    severity = Severity.HIGH if overall_rate < 0.25 else Severity.MEDIUM
+    degrading = early_rate - late_rate > HALF_DROP_THRESHOLD
+
+    summary_parts = [f"cache hit rate {overall_rate:.0%}"]
+    if degrading:
+        summary_parts.append(
+            f"degraded from {early_rate:.0%} (first half)"
+            f" to {late_rate:.0%} (second half)"
+        )
+    if cause:
+        summary_parts.append(cause)
+
+    return [
+        Finding(
+            kind=FindingKind.CACHE_HYGIENE,
+            severity=severity,
+            confidence=Confidence.MEDIUM,
+            first_turn=assistant_turns[0].turn_number,
+            last_turn=assistant_turns[-1].turn_number,
+            evidence={
+                "overall_hit_rate": round(overall_rate, 3),
+                "early_hit_rate": round(early_rate, 3),
+                "late_hit_rate": round(late_rate, 3),
+                "total_tokens": total_tokens,
+                "cause": cause,
+            },
+            cost_usd=None,
+            summary="; ".join(summary_parts),
+        )
+    ]
+
+
+def classify(trace: SessionTrace) -> list[Finding]:
+    try:
+        return _classify_impl(trace)
+    except Exception:
+        return []

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

@@ -174,6 +174,7 @@ class FindingKind(str, Enum):
     DEAD_END      = "dead_end"
     FANOUT_WASTE  = "fanout_waste"
     PROJECT_PATTERN = "project_pattern"
+    CACHE_HYGIENE = "cache_hygiene"
 
 
 KIND_LABEL: dict[FindingKind, str] = {
@@ -184,6 +185,7 @@ KIND_LABEL: dict[FindingKind, str] = {
     FindingKind.DEAD_END:      "DEAD END",
     FindingKind.FANOUT_WASTE:  "FANOUT WASTE",
     FindingKind.PROJECT_PATTERN: "PROJECT PATTERN",
+    FindingKind.CACHE_HYGIENE: "CACHE HYGIENE",
 }
 
 # Maps FindingKind to the exact ## heading emitted by its recommender patch
@@ -197,6 +199,7 @@ MANAGED_HEADINGS: dict[FindingKind, str] = {
     FindingKind.TOOL_THRASH:   "## Tool-call discipline",
     FindingKind.DEAD_END:      "## Exploration discipline",
     FindingKind.FANOUT_WASTE:  "## Fan-out discipline",
+    FindingKind.CACHE_HYGIENE: "## Cache hygiene",
 }
 
 # Project-specific patterns use a heading that embeds tool+key, so the managed

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

@@ -66,6 +66,16 @@ _FANOUT_WASTE_DIFF = """\
 +after changing something meaningful about the task — identical re-spawns waste
 +the full subagent cost with no new information."""
 
+_CACHE_HYGIENE_DIFF = """\
++## Cache hygiene
++
++Keep the prompt prefix stable across turns so Claude's KV-cache can be reused.
++Avoid changing tool definitions mid-session, keep system prompt content
++consistent, and prefer append-only context updates over rewrites. If context
++compaction fires frequently, consider splitting long sessions into shorter ones
++with a stable, cacheable preamble. A 10× cost difference separates a warm
++cache hit from a cold input read."""
+
 _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"),
@@ -74,6 +84,7 @@ _TEMPLATES: dict[FindingKind, tuple[str, str, str]] = {
     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"),
 }
 
 

cctx_cli-1.12.1/docs/quickstart-openai-agents.md → cctx_cli-1.13.0/docs/quickstart-otel.md

@@ -1,14 +1,20 @@
-# Using cctx with the OpenAI Agents SDK
+# Diagnosing other agent frameworks with cctx
 
-cctx diagnoses OpenAI Agents SDK runs the same way it diagnoses Claude Code sessions — point it at a trace file and get an autopsy.
+cctx diagnoses any agent framework that writes OpenTelemetry spans using `gen_ai.*` semantic conventions — the same way it diagnoses Claude Code sessions. Point it at a trace file and get an autopsy.
 
-## 1. Install dependencies
+**Verified frameworks:** OpenAI Agents SDK, LangGraph
+
+---
+
+## OpenAI Agents SDK
+
+### 1. Install dependencies
 
 ```bash
-pip install cctx opentelemetry-sdk
+pip install cctx-cli opentelemetry-sdk
 ```
 
-## 2. Export traces to a local file
+### 2. Export traces to a local file
 
 Add this to your agent script before running your agent. It configures OpenTelemetry to write spans to a local JSONL file.
 
@@ -84,14 +90,14 @@ provider.add_span_processor(BatchSpanProcessor(FileSpanExporter("agent_trace.jso
 # set_trace_processors([...])
 ```
 
-## 3. Run your agent
+### 3. Run your agent
 
 ```bash
 python my_agent.py
 # agent_trace.jsonl is written
 ```
 
-## 4. Diagnose the run
+### 4. Diagnose the run
 
 ```bash
 cctx autopsy agent_trace.jsonl
@@ -99,8 +105,71 @@ cctx autopsy agent_trace.jsonl
 
 `cctx autopsy` picks up the OTLP format automatically — no flags needed.
 
-## Notes
+### Notes
 
 - If your trace file contains multiple runs, cctx diagnoses the first trace by trace ID.
 - Token costs shown in the autopsy are estimates; cctx does not call the OpenAI API.
 - The exact `set_trace_processors` API varies by SDK version — check the `openai-agents` changelog if the import above doesn't work.
+
+---
+
+## LangGraph
+
+LangGraph emits `gen_ai.*` spans via the `opentelemetry-instrumentation-langchain` package from Traceloop. Pair it with the same `FileSpanExporter` above to write traces cctx can read.
+
+### 1. Install dependencies
+
+```bash
+pip install cctx-cli opentelemetry-sdk opentelemetry-instrumentation-langchain
+```
+
+### 2. Export traces to a local file
+
+Copy the `FileSpanExporter` and `_otlp_value` definitions from the OpenAI Agents SDK section above, then add the LangChain instrumentor before your graph runs:
+
+```python
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.instrumentation.langchain import LangchainInstrumentor
+
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(FileSpanExporter("agent_trace.jsonl")))
+
+LangchainInstrumentor().instrument(tracer_provider=provider)
+```
+
+### 3. Run your graph
+
+```python
+from langgraph.graph import StateGraph, END
+# ... build graph ...
+
+result = graph.invoke({"messages": [HumanMessage(content="...")]})
+# agent_trace.jsonl is written
+```
+
+### 4. Diagnose the run
+
+```bash
+cctx autopsy agent_trace.jsonl
+```
+
+### Notes
+
+- `opentelemetry-instrumentation-langchain` is maintained by [Traceloop](https://github.com/traceloop/openllmetry). It emits `gen_ai.usage.input_tokens`, `gen_ai.request.model`, and other attributes cctx maps to its canonical model.
+- LangGraph's `recursion_limit` (default 25) governs step count, not agent nesting depth. cctx handles arbitrary span depth.
+- Token costs are estimates; cctx does not call the OpenAI or Anthropic APIs during analysis.
+
+---
+
+## Other frameworks
+
+Any framework instrumented with `gen_ai.*` semantic conventions works. The minimum attributes cctx needs per span:
+
+| Span type | Required attributes |
+|---|---|
+| Agent span (`run_agent`) | `gen_ai.operation.name = "run_agent"` |
+| LLM call (`chat`) | `gen_ai.operation.name = "chat"`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.request.model` |
+| Tool call (`invoke_function`) | `gen_ai.operation.name = "invoke_function"`, `gen_ai.tool.name` |
+
+Spans are linked via `parentSpanId`. Use the `FileSpanExporter` above (or any OTLP JSON exporter that writes one `resourceSpans` batch per line) to produce a file cctx can read.

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

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