cctx-cli 1.9.0__tar.gz → 1.11.0__tar.gz

{cctx_cli-1.9.0 → cctx_cli-1.11.0}/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 <!-- version list -->
 
+## 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
+
+- Autopsy --json aggregate output for --since mode (closes #97)
+  ([#112](https://github.com/jacquardlabs/cctx/pull/112),
+  [`86b10e0`](https://github.com/jacquardlabs/cctx/commit/86b10e0787efa99e9af251e979e311053d7b8b72))
+
+
 ## v1.9.0 (2026-06-11)
 
 ### Bug Fixes

{cctx_cli-1.9.0 → cctx_cli-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.9.0
+Version: 1.11.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.9.0 → cctx_cli-1.11.0}/cctx/__init__.py

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

{cctx_cli-1.9.0 → cctx_cli-1.11.0}/cctx/cli.py

@@ -9,6 +9,7 @@ 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
 
@@ -292,7 +293,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 +314,7 @@ def autopsy(
     top_n: int | None,
     turn_num: int | None,
     json_out: bool,
+    quiet: bool,
 ) -> None:
     """Diagnose a session or project directory.
 
@@ -326,8 +336,6 @@ def autopsy(
         raise click.UsageError("--turn is not supported with --since.")
     if until_date is not None and since is None:
         raise click.UsageError("--until requires --since.")
-    if json_out and since is not None:
-        raise click.UsageError("--json is not supported with --since.")
 
     if target is None:
         if not latest:
@@ -392,8 +400,14 @@ def autopsy(
             patches=patches,
             project_patterns=patterns,
         )
-        render_aggregate(report)
-        _aggregate_drilldown(report, diagnoses)
+        if json_out:
+            import json as _json
+
+            from cctx.exporters.jsonl import export_aggregate as _export_agg
+            click.echo(_json.dumps(_json.loads(_export_agg(report)), indent=2))
+        else:
+            render_aggregate(report)
+            _aggregate_drilldown(report, diagnoses)
     else:
         # Single-session path
         if target.is_dir():
@@ -404,7 +418,11 @@ def autopsy(
         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
@@ -725,3 +743,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.9.0 → cctx_cli-1.11.0}/cctx/exporters/jsonl.py

@@ -5,7 +5,7 @@ import json
 from typing import IO, TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from cctx.models import Diagnosis, SessionTrace
+    from cctx.models import AggregateReport, Diagnosis, SessionTrace
 
 
 def export_diagnosis(
@@ -64,6 +64,50 @@ def export_diagnosis(
     return json.dumps(obj)
 
 
+def export_aggregate(report: AggregateReport) -> str:
+    """Serialize an AggregateReport to a JSON string."""
+    by_kind = {
+        k.value: {
+            "session_count": v.session_count,
+            "total_waste_usd": v.total_waste_usd,
+            "example_summaries": v.example_summaries,
+        }
+        for k, v in report.by_kind.items()
+    }
+    patches = [
+        {
+            "target_file": p.target_file,
+            "finding_kind": p.finding_kind.value,
+            "description": p.description,
+            "evidence_summary": p.evidence_summary,
+        }
+        for p in report.patches
+    ]
+    project_patterns = [
+        {
+            "tool_name": pp.tool_name,
+            "failure_key": pp.failure_key,
+            "fix_key": pp.fix_key,
+            "session_count": pp.session_count,
+            "avg_wasted_turns": pp.avg_wasted_turns,
+            "total_waste_usd": pp.total_waste_usd,
+            "example_sessions": pp.example_sessions,
+        }
+        for pp in report.project_patterns
+    ]
+    obj = {
+        "period_label": report.period_label,
+        "sessions_analysed": report.sessions_analysed,
+        "sessions_with_findings": report.sessions_with_findings,
+        "total_cost_usd": report.total_cost_usd,
+        "waste_cost_usd": report.waste_cost_usd,
+        "by_kind": by_kind,
+        "patches": patches,
+        "project_patterns": project_patterns,
+    }
+    return json.dumps(obj)
+
+
 def write(
     diagnoses: list[tuple[Diagnosis, SessionTrace]],
     out: IO[str],

cctx_cli-1.11.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)

{cctx_cli-1.9.0 → cctx_cli-1.11.0}/pyproject.toml

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

{cctx_cli-1.9.0 → cctx_cli-1.11.0}/tests/test_cli.py

@@ -488,17 +488,42 @@ def test_autopsy_json_outputs_valid_json(runner, session_jsonl):
     assert "findings" in data
 
 
-def test_autopsy_json_incompatible_with_since(runner, tmp_path):
-    """--json + --since → non-zero exit (UsageError)."""
+def test_autopsy_json_aggregate_outputs_valid_json(runner, tmp_path):
+    """--json + --since → valid aggregate JSON with expected top-level keys."""
     from cctx.cli import cli
 
     project_dir = tmp_path / "-Users-test-Projects-demo"
     project_dir.mkdir()
 
+    session_id = "json-agg-test-01"
+    line = {
+        "type": "user",
+        "uuid": f"{session_id}-u1",
+        "parentUuid": None,
+        "isSidechain": False,
+        "timestamp": "2026-05-14T10:00:00.000Z",
+        "sessionId": session_id,
+        "version": "2.1.138",
+        "cwd": "/Users/test/Projects/demo",
+        "gitBranch": "main",
+        "userType": "external",
+        "entrypoint": "cli",
+        "message": {"role": "user", "content": "hello"},
+    }
+    (project_dir / f"{session_id}.jsonl").write_text(json.dumps(line) + "\n")
+
     result = runner.invoke(
         cli, ["autopsy", str(project_dir), "--since", "7", "--json"],
+        catch_exceptions=False,
     )
-    assert result.exit_code != 0
+    assert result.exit_code == 0
+    data = json.loads(result.output)
+    assert "sessions_analysed" in data
+    assert "total_cost_usd" in data
+    assert "waste_cost_usd" in data
+    assert "by_kind" in data
+    assert "patches" in data
+    assert "project_patterns" in data
 
 
 def test_autopsy_json_contains_cost(runner, session_jsonl):