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

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

@@ -2,6 +2,21 @@
 
 <!-- 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.10.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.10.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.10.0"
+__version__ = "1.11.0"

{cctx_cli-1.10.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.
 
@@ -408,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
@@ -729,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.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.10.0 → cctx_cli-1.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cctx-cli"
-version = "1.10.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.11.0/tests/test_init.py

@@ -0,0 +1,323 @@
+"""Tests for cctx init command and hook_installer module."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+
+@pytest.fixture
+def runner():
+    return CliRunner()
+
+
+@pytest.fixture
+def settings_dir(tmp_path):
+    d = tmp_path / ".claude"
+    d.mkdir()
+    return d
+
+
+# ---------------------------------------------------------------------------
+# hook_installer unit tests
+# ---------------------------------------------------------------------------
+
+
+def test_install_creates_settings_file(tmp_path, monkeypatch):
+    """install() writes .claude/settings.json with the hook entry."""
+    monkeypatch.chdir(tmp_path)
+    from cctx import hook_installer
+
+    result = hook_installer.install()
+    path = Path(".claude/settings.json")
+    assert path.exists()
+    data = json.loads(path.read_text())
+    session_end = data["hooks"]["SessionEnd"]
+    assert len(session_end) == 1
+    inner = session_end[0]["hooks"][0]
+    assert inner["type"] == "command"
+    assert "cctx autopsy --latest --quiet" in inner["command"]
+    assert "cctx SessionEnd" in inner["description"]
+    assert result == str(path)
+
+
+def test_install_idempotent(tmp_path, monkeypatch):
+    """Running install() twice does not duplicate the hook."""
+    monkeypatch.chdir(tmp_path)
+    from cctx import hook_installer
+
+    hook_installer.install()
+    result = hook_installer.install()
+    assert result == "already_installed"
+
+    path = Path(".claude/settings.json")
+    data = json.loads(path.read_text())
+    assert len(data["hooks"]["SessionEnd"]) == 1
+
+
+def test_install_preserves_existing_settings(tmp_path, monkeypatch):
+    """install() merges into existing settings without clobbering other keys."""
+    monkeypatch.chdir(tmp_path)
+    from cctx import hook_installer
+
+    settings_path = tmp_path / ".claude" / "settings.json"
+    settings_path.parent.mkdir()
+    existing = {
+        "permissions": {"allow": ["Bash(git*)"]},
+        "hooks": {
+            "PreToolUse": [
+                {"matcher": "Bash", "hooks": [{"type": "command", "command": "echo pre"}]}
+            ]
+        },
+    }
+    settings_path.write_text(json.dumps(existing))
+
+    hook_installer.install()
+    data = json.loads(settings_path.read_text())
+
+    # Existing keys preserved
+    assert data["permissions"]["allow"] == ["Bash(git*)"]
+    assert "PreToolUse" in data["hooks"]
+    # New hook added
+    assert "SessionEnd" in data["hooks"]
+    assert len(data["hooks"]["SessionEnd"]) == 1
+
+
+def test_install_force_replaces_hook(tmp_path, monkeypatch):
+    """install(force=True) replaces existing hook without duplicating."""
+    monkeypatch.chdir(tmp_path)
+    from cctx import hook_installer
+
+    hook_installer.install()
+    result = hook_installer.install(force=True)
+
+    path = Path(".claude/settings.json")
+    data = json.loads(path.read_text())
+    assert len(data["hooks"]["SessionEnd"]) == 1
+    assert result != "already_installed"
+
+
+def test_remove_cleans_up(tmp_path, monkeypatch):
+    """remove() deletes the hook and prunes empty keys."""
+    monkeypatch.chdir(tmp_path)
+    from cctx import hook_installer
+
+    hook_installer.install()
+    result = hook_installer.remove()
+
+    path = Path(".claude/settings.json")
+    assert result is not None
+    data = json.loads(path.read_text())
+    assert "hooks" not in data
+
+
+def test_remove_preserves_other_hooks(tmp_path, monkeypatch):
+    """remove() only removes the cctx hook, leaving other SessionEnd hooks."""
+    monkeypatch.chdir(tmp_path)
+    from cctx import hook_installer
+
+    settings_path = tmp_path / ".claude" / "settings.json"
+    settings_path.parent.mkdir()
+    other_hook = {"hooks": [{"type": "command", "command": "echo other"}]}
+    settings_path.write_text(json.dumps({
+        "hooks": {"SessionEnd": [other_hook]}
+    }))
+
+    hook_installer.install()
+    hook_installer.remove()
+
+    data = json.loads(settings_path.read_text())
+    session_end = data["hooks"]["SessionEnd"]
+    assert len(session_end) == 1
+    assert session_end[0]["hooks"][0]["command"] == "echo other"
+
+
+def test_remove_not_found_returns_none(tmp_path, monkeypatch):
+    """remove() when hook is not installed returns None without error."""
+    monkeypatch.chdir(tmp_path)
+    from cctx import hook_installer
+
+    assert hook_installer.remove() is None
+
+
+def test_is_installed_false_before_install(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    from cctx import hook_installer
+
+    assert not hook_installer.is_installed()
+
+
+def test_is_installed_true_after_install(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    from cctx import hook_installer
+
+    hook_installer.install()
+    assert hook_installer.is_installed()
+
+
+def test_invalid_json_raises(tmp_path, monkeypatch):
+    """Corrupt settings.json → ValueError, not a silent overwrite."""
+    monkeypatch.chdir(tmp_path)
+    from cctx import hook_installer
+
+    path = tmp_path / ".claude" / "settings.json"
+    path.parent.mkdir()
+    path.write_text("{ not valid json }")
+
+    with pytest.raises(ValueError, match="Invalid JSON"):
+        hook_installer.install()
+
+
+def test_global_scope_writes_to_home(tmp_path, monkeypatch):
+    """--global writes to ~/.claude/settings.json."""
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: fake_home))
+    from cctx import hook_installer
+
+    hook_installer.install(global_=True)
+    path = fake_home / ".claude" / "settings.json"
+    assert path.exists()
+    data = json.loads(path.read_text())
+    assert "SessionEnd" in data["hooks"]
+
+
+# ---------------------------------------------------------------------------
+# CLI integration tests (cctx init)
+# ---------------------------------------------------------------------------
+
+
+def test_init_installs_hook(runner, tmp_path):
+    """cctx init writes the hook and prints confirmation."""
+    from cctx.cli import cli
+
+    result = runner.invoke(cli, ["init"], catch_exceptions=False, env={"PWD": str(tmp_path)})
+    # Note: monkeypatching cwd is simpler in unit tests; CLI uses Path(".claude/...")
+    # relative to cwd — just check exit code and output shape
+    assert result.exit_code == 0
+    assert (
+        "✓" in result.output
+        or "already" in result.output.lower()
+        or "installed" in result.output.lower()
+    )
+
+
+def test_init_idempotent_cli(runner, tmp_path, monkeypatch):
+    """cctx init twice → second run reports already installed."""
+    monkeypatch.chdir(tmp_path)
+    from cctx.cli import cli
+
+    runner.invoke(cli, ["init"], catch_exceptions=False)
+    result = runner.invoke(cli, ["init"], catch_exceptions=False)
+    assert result.exit_code == 0
+    assert "already" in result.output.lower()
+
+
+def test_init_remove_cli(runner, tmp_path, monkeypatch):
+    """cctx init --remove cleans up the hook."""
+    monkeypatch.chdir(tmp_path)
+    from cctx.cli import cli
+
+    runner.invoke(cli, ["init"], catch_exceptions=False)
+    result = runner.invoke(cli, ["init", "--remove"], catch_exceptions=False)
+    assert result.exit_code == 0
+    assert "removed" in result.output.lower()
+
+
+def test_init_remove_not_installed_cli(runner, tmp_path, monkeypatch):
+    """cctx init --remove when not installed exits 0 with a friendly message."""
+    monkeypatch.chdir(tmp_path)
+    from cctx.cli import cli
+
+    result = runner.invoke(cli, ["init", "--remove"], catch_exceptions=False)
+    assert result.exit_code == 0
+    assert "nothing" in result.output.lower() or "not found" in result.output.lower()
+
+
+def test_init_force_and_remove_errors(runner, tmp_path, monkeypatch):
+    """--force --remove together → UsageError."""
+    monkeypatch.chdir(tmp_path)
+    from cctx.cli import cli
+
+    result = runner.invoke(cli, ["init", "--force", "--remove"])
+    assert result.exit_code != 0
+
+
+# ---------------------------------------------------------------------------
+# autopsy --quiet tests
+# ---------------------------------------------------------------------------
+
+
+def _make_session_file(tmp_path: Path, session_id: str) -> Path:
+    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"},
+    }
+    path = tmp_path / f"{session_id}.jsonl"
+    path.write_text(json.dumps(line) + "\n")
+    return path
+
+
+def test_autopsy_quiet_clean_no_output(runner, tmp_path):
+    """--quiet on a clean session emits nothing and exits 0."""
+    from cctx.cli import cli
+
+    session = _make_session_file(tmp_path, "quiet-clean-01")
+    result = runner.invoke(cli, ["autopsy", str(session), "--quiet"], catch_exceptions=False)
+    assert result.exit_code == 0
+    assert result.output.strip() == ""
+
+
+def test_autopsy_quiet_with_findings_emits_verdict(runner, tmp_path, monkeypatch):
+    """--quiet on a session with findings emits one verdict line."""
+    from cctx.cli import cli
+    from cctx.models import Confidence, Finding, FindingKind, Severity
+
+    session = _make_session_file(tmp_path, "quiet-dirty-01")
+
+    # Inject a finding via monkeypatch so we don't need a real problematic session
+    from datetime import datetime, timezone
+
+    from cctx import diagnostician
+    from cctx.models import Diagnosis
+
+    def fake_run(trace):
+        return Diagnosis(
+            session_id=trace.session_id,
+            findings=[
+                Finding(
+                    kind=FindingKind.RETRY_LOOP,
+                    severity=Severity.HIGH,
+                    confidence=Confidence.HIGH,
+                    first_turn=1,
+                    last_turn=2,
+                    evidence={},
+                    cost_usd=0.01,
+                    summary="test finding",
+                )
+            ],
+            inflection_turn=1,
+            patches=[],
+            total_cost_usd=0.10,
+            waste_cost_usd=0.01,
+            analysed_at=datetime(2026, 5, 14, 10, 0, tzinfo=timezone.utc),
+        )
+
+    monkeypatch.setattr(diagnostician, "run", fake_run)
+
+    result = runner.invoke(cli, ["autopsy", str(session), "--quiet"], catch_exceptions=False)
+    assert result.exit_code == 0
+    assert "finding" in result.output.lower()
+    assert "retry_loop" in result.output.lower()