cctx-cli 1.10.0__tar.gz → 1.12.0__tar.gz

{cctx_cli-1.10.0 → cctx_cli-1.12.0}/CHANGELOG.md

@@ -2,6 +2,85 @@
 
 <!-- version list -->
 
+## v1.12.0 (2026-06-20)
+
+### Bug Fixes
+
+- Otel parser — per-trace warnings, multiple-root warning, full span list for subagent turns
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- Ruff F401 + I001 in test_otel_parser.py ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+### Documentation
+
+- OTEL parser design spec — OpenAI Agents SDK support via parsers/otel.py
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- OTEL parser implementation plan ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- Quickstart guide for OpenAI Agents SDK + cctx OTEL integration
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+### Features
+
+- _detect_source() — auto-detect Claude Code vs OTEL trace format
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- OpenAI Agents SDK support via OTEL parser ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- OTEL parser skeleton — span loading and session trace construction
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- Wire OTEL auto-detection into autopsy — cctx autopsy <otel.jsonl> just works
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+### Testing
+
+- Add OTLP JSONL fixtures for otel parser (handoff + fanout)
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- OTEL parser error handling — malformed JSON, unknown spans, empty file
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- Verify child AgentSpan → subagents mapping (handoff + fan-out)
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- Verify FunctionSpan → ToolUse + ToolResult mapping
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+- Verify GenerationSpan → Turn mapping for OTEL parser
+  ([#116](https://github.com/jacquardlabs/cctx/pull/116),
+  [`a6b56b6`](https://github.com/jacquardlabs/cctx/commit/a6b56b61ccff5493dd26f375a698eb59aff62272))
+
+
+## v1.11.0 (2026-06-11)
+
+### Bug Fixes
+
+- Ruff E501 + I001 in test_init.py (line length + import order)
+  ([#113](https://github.com/jacquardlabs/cctx/pull/113),
+  [`a04426e`](https://github.com/jacquardlabs/cctx/commit/a04426ef62cfeaa4ba7ea392bdf0dd49975cffbb))
+
+### Features
+
+- Cctx init — SessionEnd hook installer + autopsy --quiet (closes #92)
+  ([#113](https://github.com/jacquardlabs/cctx/pull/113),
+  [`a04426e`](https://github.com/jacquardlabs/cctx/commit/a04426ef62cfeaa4ba7ea392bdf0dd49975cffbb))
+
+
 ## v1.10.0 (2026-06-11)
 
 ### Features

{cctx_cli-1.10.0 → cctx_cli-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.10.0
+Version: 1.12.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.10.0 → cctx_cli-1.12.0}/cctx/__init__.py

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

{cctx_cli-1.10.0 → cctx_cli-1.12.0}/cctx/cli.py

@@ -9,9 +9,11 @@ Commands:
   cctx harvest <session>           Apply autopsy patches to CLAUDE.md
   cctx harvest <project> --since   Cross-session harvest
   cctx watch [project]             Live waste signals during an active session
+  cctx init                        Install opt-in SessionEnd hook for auto-diagnostics
 """
 from __future__ import annotations
 
+import json as _json
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import IO
@@ -178,6 +180,48 @@ def _render_check_findings(findings: list, target_dir: Path) -> None:
         con.print(f"  {badge:<6}  {f.heading}  {label}: {f.detail}")
 
 
+_CLAUDE_CODE_LINE_TYPES = frozenset({
+    "user", "assistant", "system", "attachment",
+    "last-prompt", "permission-mode", "ai-title", "custom-title",
+    "queue-operation", "file-history-snapshot", "pr-link",
+})
+
+
+def _detect_source(path: Path) -> str:
+    """Sniff first non-empty lines to detect trace format.
+
+    Returns "claude_code" or "otel".
+    Raises click.UsageError if the format cannot be determined.
+    """
+    try:
+        with path.open(encoding="utf-8", errors="replace") as f:
+            for _ in range(5):
+                line = f.readline()
+                if not line:
+                    break
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = _json.loads(line)
+                except _json.JSONDecodeError:
+                    continue
+                if "resourceSpans" in obj:
+                    return "otel"
+                if "traceId" in obj and "spanId" in obj:
+                    return "otel"
+                line_type = obj.get("type")
+                if isinstance(line_type, str) and line_type in _CLAUDE_CODE_LINE_TYPES:
+                    return "claude_code"
+    except OSError as exc:
+        raise click.UsageError(f"Cannot read file: {path}: {exc}") from exc
+
+    raise click.UsageError(
+        f"Cannot determine trace format for {path}.\n"
+        "Expected a Claude Code JSONL session file or an OTLP JSON trace export."
+    )
+
+
 @click.group()
 def cli() -> None:
     """cctx — find out why your Claude Code session went sideways."""
@@ -292,7 +336,15 @@ def ls(project: Path | None) -> None:
     "json_out",
     is_flag=True,
     default=False,
-    help="Output diagnosis as JSON to stdout (single-session only).",
+    help="Output diagnosis (or aggregate) as JSON to stdout.",
+)
+@click.option(
+    "--quiet",
+    "quiet",
+    is_flag=True,
+    default=False,
+    help="Print one verdict line only when findings exist; nothing if clean. "
+         "Designed for SessionEnd hook use (cctx init).",
 )
 def autopsy(
     target: Path | None,
@@ -305,6 +357,7 @@ def autopsy(
     top_n: int | None,
     turn_num: int | None,
     json_out: bool,
+    quiet: bool,
 ) -> None:
     """Diagnose a session or project directory.
 
@@ -405,10 +458,22 @@ def autopsy(
                 "TARGET is a directory. Use --since N for cross-session mode, "
                 "or pass a .jsonl file directly."
             )
-        trace = tokenize_session(parse_session(target))
+        source = _detect_source(target)
+        if source == "otel":
+            from cctx.parsers.otel import parse_otel_file as _parse_otel_file
+            otel_traces = _parse_otel_file(target)
+            if not otel_traces:
+                raise click.UsageError(f"No traces found in {target}")
+            trace = tokenize_session(otel_traces[0])
+        else:
+            trace = tokenize_session(parse_session(target))
         diagnosis = diagnostician.run(trace)
         diagnosis = claude_md.generate(diagnosis)
-        if json_out:
+        if quiet:
+            if diagnosis.findings:
+                kinds = list(dict.fromkeys(f.kind.value for f in diagnosis.findings))
+                click.echo(f"{len(diagnosis.findings)} finding(s): {', '.join(kinds)}")
+        elif json_out:
             import json as _json
 
             from cctx.exporters.jsonl import export_diagnosis as _export_diag
@@ -729,3 +794,58 @@ def watch(target: Path | None) -> None:
     """
     from cctx.watcher import watch as _watch
     _watch(target)
+
+
+@cli.command("init")
+@click.option(
+    "--global",
+    "global_",
+    is_flag=True,
+    default=False,
+    help="Install to ~/.claude/settings.json (user scope) instead of .claude/settings.json.",
+)
+@click.option(
+    "--remove",
+    "remove_",
+    is_flag=True,
+    default=False,
+    help="Remove the SessionEnd hook instead of installing it.",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Reinstall even if hook is already present.",
+)
+def init_cmd(global_: bool, remove_: bool, force: bool) -> None:
+    """Install an opt-in SessionEnd hook for automatic post-session diagnostics.
+
+    Writes a hook to .claude/settings.json (project) or ~/.claude/settings.json
+    (--global) that runs 'cctx autopsy --latest --quiet' when a Claude Code
+    session ends. Output appears only when findings exist.
+
+    Idempotent — running twice does not duplicate the hook.
+    """
+    from cctx import hook_installer
+
+    if force and remove_:
+        raise click.UsageError("--force and --remove are mutually exclusive.")
+
+    scope = "~/.claude/settings.json" if global_ else ".claude/settings.json"
+
+    if remove_:
+        path = hook_installer.remove(global_=global_)
+        if path is None:
+            click.echo(f"No cctx hook found in {scope} — nothing to remove.")
+        else:
+            click.echo(f"✓ SessionEnd hook removed from {scope}")
+        return
+
+    result = hook_installer.install(global_=global_, force=force)
+    if result == "already_installed":
+        click.echo(f"! SessionEnd hook already installed in {scope}")
+        click.echo("  Use 'cctx init --force' to reinstall.")
+    else:
+        click.echo(f"✓ SessionEnd hook installed to {scope}")
+        remove_flag = "--global --remove" if global_ else "--remove"
+        click.echo(f"  Run 'cctx init {remove_flag}' to uninstall.")

cctx_cli-1.12.0/cctx/hook_installer.py

@@ -0,0 +1,101 @@
+"""Settings-merge hook installer — install/remove the cctx SessionEnd hook.
+
+Reads, merges, and writes ~/.claude/settings.json or .claude/settings.json
+without touching any other keys. Idempotent: fingerprinted by the hook's
+description field so a double-install is a no-op.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+HOOK_DESCRIPTION = "cctx SessionEnd hook (diagnostics on session exit)"
+HOOK_COMMAND = "cctx autopsy --latest --quiet"
+
+
+def settings_path(global_: bool) -> Path:
+    if global_:
+        return Path.home() / ".claude" / "settings.json"
+    return Path(".claude") / "settings.json"
+
+
+def _load(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON in {path}: {exc}") from exc
+
+
+def _save(path: Path, settings: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+    tmp.replace(path)
+
+
+def _find_hook(session_end: list[dict[str, Any]]) -> int | None:
+    """Return the index of the cctx hook group in the SessionEnd array, or None."""
+    for i, group in enumerate(session_end):
+        for h in group.get("hooks", []):
+            desc = h.get("description", "")
+            if isinstance(desc, str) and "cctx SessionEnd" in desc:
+                return i
+    return None
+
+
+def _hook_entry() -> dict[str, Any]:
+    return {
+        "hooks": [
+            {
+                "type": "command",
+                "command": HOOK_COMMAND,
+                "async": True,
+                "description": HOOK_DESCRIPTION,
+            }
+        ]
+    }
+
+
+def is_installed(global_: bool = False) -> bool:
+    path = settings_path(global_)
+    settings = _load(path)
+    session_end = settings.get("hooks", {}).get("SessionEnd", [])
+    return _find_hook(session_end) is not None
+
+
+def install(global_: bool = False, force: bool = False) -> str:
+    """Install the hook. Returns "already_installed" or the path written."""
+    path = settings_path(global_)
+    settings = _load(path)
+    hooks = settings.setdefault("hooks", {})
+    session_end = hooks.setdefault("SessionEnd", [])
+    idx = _find_hook(session_end)
+    if idx is not None and not force:
+        return "already_installed"
+    if idx is not None:
+        session_end[idx] = _hook_entry()
+    else:
+        session_end.append(_hook_entry())
+    _save(path, settings)
+    return str(path)
+
+
+def remove(global_: bool = False) -> str | None:
+    """Remove the hook. Returns the path written, or None if not found."""
+    path = settings_path(global_)
+    settings = _load(path)
+    hooks = settings.get("hooks", {})
+    session_end = hooks.get("SessionEnd", [])
+    idx = _find_hook(session_end)
+    if idx is None:
+        return None
+    session_end.pop(idx)
+    if not session_end:
+        del hooks["SessionEnd"]
+    if not hooks:
+        del settings["hooks"]
+    _save(path, settings)
+    return str(path)