cctx-cli 0.1.0__py3-none-any.whl

cctx/__init__.py

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

cctx/cli.py

@@ -0,0 +1,375 @@
+"""cctx CLI — click + rich-click entry point.
+
+Commands:
+  cctx ls [project]                List projects or sessions
+  cctx autopsy <session>           Single-session diagnosis
+  cctx autopsy <project> --since   Cross-session aggregation
+  cctx export <session>            Export session data as JSONL or CSV
+  cctx trace <session>             Interactive TUI trace viewer
+  cctx harvest <session>           Apply autopsy patches to CLAUDE.md
+  cctx harvest <project> --since   Cross-session harvest
+"""
+from __future__ import annotations
+
+from datetime import timedelta
+from pathlib import Path
+
+import rich_click as click
+
+from cctx import diagnostician
+from cctx.diagnostician import aggregate
+from cctx.discovery import complete_project as _complete_project
+from cctx.models import AggregateReport
+from cctx.parsers.claude_code import parse_session
+from cctx.recommender import claude_md
+from cctx.recommender import evidence as evidence_mod
+from cctx.renderers.terminal import (
+    render_aggregate,
+    render_diagnosis,
+    render_harvest_results,
+    render_projects,
+    render_sessions,
+)
+from cctx.tokenizer import tokenize_session
+
+click.rich_click.USE_RICH_MARKUP = True
+click.rich_click.SHOW_ARGUMENTS = True
+
+
+@click.group()
+def cli() -> None:
+    """cctx — find out why your Claude Code session went sideways."""
+
+
+@cli.command("ls")
+@click.argument(
+    "project",
+    required=False,
+    type=click.Path(exists=True, path_type=Path),
+    shell_complete=lambda c, p, i: _complete_project(c, p, i),
+)
+def ls(project: Path | None) -> None:
+    """List Claude Code projects and sessions.
+
+    With no arguments, lists all projects in ~/.claude/projects/.
+
+    With PROJECT (a local project directory), lists sessions for that project.
+    """
+    from cctx.discovery import ProjectInfo, find_project_dir, list_projects, list_sessions
+
+    if project is None:
+        projects = list_projects()
+        render_projects(projects)
+    else:
+        cwd = project if project.is_dir() else project.parent
+        project_dir = find_project_dir(cwd)
+        if project_dir is None:
+            raise click.UsageError(
+                f"No Claude Code sessions found for {cwd}.\n"
+                "Check that ~/.claude/projects/ contains a matching directory."
+            )
+        sessions = list_sessions(project_dir)
+        info = ProjectInfo(
+            project_dir=project_dir,
+            display_name=str(cwd).replace(str(Path.home()), "~"),
+            sessions=sessions,
+        )
+        render_sessions(info)
+
+
+@cli.command()
+@click.argument(
+    "target",
+    required=False,
+    type=click.Path(path_type=Path),
+    shell_complete=lambda c, p, i: _complete_project(c, p, i),
+)
+@click.option(
+    "--since",
+    default=None,
+    metavar="DAYS",
+    type=int,
+    help="Cross-session mode: analyse all sessions modified within the last N days.",
+)
+@click.option(
+    "--latest",
+    is_flag=True,
+    default=False,
+    help="Diagnose the most recent session in TARGET project (default: cwd).",
+)
+@click.option(
+    "--html",
+    "html_out",
+    default=None,
+    metavar="FILE",
+    type=click.Path(path_type=Path),
+    help="Write a self-contained HTML report to FILE (single-session only).",
+)
+def autopsy(
+    target: Path | None,
+    since: int | None,
+    latest: bool,
+    html_out: Path | None,
+) -> None:
+    """Diagnose a session or project directory.
+
+    TARGET is a session JSONL file for single-session diagnosis,
+    or a project directory for --since cross-session aggregation.
+
+    Use --latest to automatically pick the most recent session in a project.
+    """
+    from cctx.discovery import find_project_dir
+    from cctx.discovery import latest_session as _latest_session
+
+    if latest and since is not None:
+        raise click.UsageError("--latest and --since are mutually exclusive.")
+
+    if target is None:
+        if not latest:
+            raise click.UsageError(
+                "TARGET is required. Pass a session .jsonl file, a project directory, "
+                "or use --latest to pick the most recent session."
+            )
+        target = Path.cwd()
+
+    if not target.exists():
+        raise click.UsageError(f"Path does not exist: {target}")
+
+    # Resolve a directory to its latest session (explicit --latest or implicit when
+    # a directory is passed without --since).
+    if target.is_dir() and since is None:
+        # Accept both local project dirs (~/Projects/foo) and encoded claude dirs
+        session = _latest_session(target)  # works if target IS the .claude/projects dir
+        if session is None:
+            project_dir = find_project_dir(target)
+            if project_dir is not None:
+                session = _latest_session(project_dir)
+        if session is None:
+            raise click.UsageError(
+                f"No Claude Code sessions found for {target}.\n"
+                "Check that ~/.claude/projects/ contains a matching directory."
+            )
+        target = session
+
+    if since is not None:
+        if html_out is not None:
+            raise click.UsageError("--html is not supported with --since.")
+        # Cross-session path
+        project_dir = target if target.is_dir() else target.parent
+        window = timedelta(days=since)
+        diagnoses = aggregate.run(project_dir, window=window)
+        ev = evidence_mod.accumulate(diagnoses)
+        patches = claude_md.generate_from_evidence(ev)
+        report = AggregateReport(
+            window=window,
+            sessions_analysed=len(diagnoses),
+            sessions_with_findings=sum(1 for d in diagnoses if d.findings),
+            total_cost_usd=sum(d.total_cost_usd for d in diagnoses),
+            waste_cost_usd=sum(d.waste_cost_usd for d in diagnoses),
+            by_kind=ev,
+            patches=patches,
+        )
+        render_aggregate(report)
+    else:
+        # Single-session path
+        if target.is_dir():
+            raise click.UsageError(
+                "TARGET is a directory. Use --since N for cross-session mode, "
+                "or pass a .jsonl file directly."
+            )
+        trace = tokenize_session(parse_session(target))
+        diagnosis = diagnostician.run(trace)
+        diagnosis = claude_md.generate(diagnosis)
+        if html_out is not None:
+            from cctx.renderers.report import render_html
+            html_out.write_text(render_html(diagnosis, trace), encoding="utf-8")
+            click.echo(f"HTML report written to {html_out}")
+        else:
+            render_diagnosis(diagnosis, session_path=target)
+
+
+@cli.command()
+@click.argument("target", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["jsonl", "csv"]),
+    default="jsonl",
+    show_default=True,
+    help="Output format: jsonl (one object per session) or csv (one row per turn).",
+)
+@click.option(
+    "--out",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Write output to FILE instead of stdout.",
+)
+@click.option(
+    "--no-content",
+    is_flag=True,
+    default=False,
+    help="Omit text content (finding summaries, patch diffs).",
+)
+def export(target: Path, fmt: str, out: Path | None, no_content: bool) -> None:
+    """Export session data in machine-readable format.
+
+    TARGET is a session JSONL file.
+    """
+    import sys
+
+    from cctx.exporters import csv as csv_mod
+    from cctx.exporters import jsonl as jsonl_mod
+
+    trace = tokenize_session(parse_session(target))
+    diagnosis = diagnostician.run(trace)
+    diagnosis = claude_md.generate(diagnosis)
+    pairs = [(diagnosis, trace)]
+
+    if out is not None:
+        with open(out, "w", encoding="utf-8") as fh:
+            if fmt == "jsonl":
+                jsonl_mod.write(pairs, fh, include_content=not no_content)
+            else:
+                csv_mod.write(pairs, fh)
+    elif fmt == "jsonl":
+        jsonl_mod.write(pairs, sys.stdout, include_content=not no_content)
+    else:
+        csv_mod.write(pairs, sys.stdout)
+
+
+@cli.command()
+@click.argument(
+    "target",
+    required=False,
+    type=click.Path(path_type=Path),
+)
+@click.option(
+    "--latest",
+    is_flag=True,
+    default=False,
+    help="Open the most recent session in TARGET project (default: cwd).",
+)
+def trace(target: Path | None, latest: bool) -> None:
+    """Open an interactive TUI trace viewer for a session.
+
+    TARGET is a session JSONL file or project directory.
+    Use --latest to automatically pick the most recent session.
+    """
+    from cctx.discovery import find_project_dir
+    from cctx.discovery import latest_session as _latest_session
+    from cctx.renderers.trace_tui import launch
+
+    if target is None:
+        if not latest:
+            raise click.UsageError(
+                "TARGET is required. Pass a session .jsonl file, a project directory, "
+                "or use --latest to pick the most recent session."
+            )
+        target = Path.cwd()
+
+    if not target.exists():
+        raise click.UsageError(f"Path does not exist: {target}")
+
+    if target.is_dir():
+        session_path = _latest_session(target)
+        if session_path is None:
+            project_dir = find_project_dir(target)
+            if project_dir is not None:
+                session_path = _latest_session(project_dir)
+        if session_path is None:
+            raise click.UsageError(
+                f"No Claude Code sessions found for {target}.\n"
+                "Check that ~/.claude/projects/ contains a matching directory."
+            )
+        target = session_path
+
+    session = tokenize_session(parse_session(target))
+    diagnosis = diagnostician.run(session)
+    diagnosis = claude_md.generate(diagnosis)
+    launch(session, diagnosis)
+
+
+@cli.command()
+@click.argument("target", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--since",
+    default=None,
+    metavar="DAYS",
+    type=int,
+    help="Cross-session mode: apply patches from sessions in the last N days.",
+)
+@click.option(
+    "--apply",
+    "apply_mode",
+    is_flag=True,
+    default=False,
+    help="Apply patches without interactive confirmation.",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Print what would change and exit 0; do not write.",
+)
+@click.option(
+    "--target-dir",
+    default=None,
+    type=click.Path(file_okay=False, path_type=Path),
+    help="Directory containing CLAUDE.md (default: cwd).",
+)
+def harvest(
+    target: Path,
+    since: int | None,
+    apply_mode: bool,
+    dry_run: bool,
+    target_dir: Path | None,
+) -> None:
+    """Apply autopsy patches to CLAUDE.md."""
+    from cctx.harvest import apply_patches, preview_patches
+
+    if apply_mode and dry_run:
+        raise click.UsageError("--apply and --dry-run are mutually exclusive.")
+
+    resolved_dir = target_dir or Path.cwd()
+    claude_md_path = resolved_dir / "CLAUDE.md"
+    click.echo(f"Target: {claude_md_path}")
+
+    if since is not None:
+        project_dir = target if target.is_dir() else target.parent
+        window = timedelta(days=since)
+        diagnoses = aggregate.run(project_dir, window=window)
+        ev = evidence_mod.accumulate(diagnoses)
+        patches = claude_md.generate_from_evidence(ev)
+    else:
+        if target.is_dir():
+            raise click.UsageError(
+                "TARGET is a directory. Use --since N for cross-session mode, "
+                "or pass a .jsonl file directly."
+            )
+        trace = tokenize_session(parse_session(target))
+        diagnosis = diagnostician.run(trace)
+        diagnosis = claude_md.generate(diagnosis)
+        patches = diagnosis.patches
+
+    if not patches:
+        render_harvest_results([], dry_run=dry_run)
+        return
+
+    if dry_run:
+        results = preview_patches(patches, resolved_dir)
+        render_harvest_results(results, dry_run=True)
+        return
+
+    if apply_mode:
+        results = apply_patches(patches, resolved_dir)
+        render_harvest_results(results)
+        return
+
+    preview = preview_patches(patches, resolved_dir)
+    render_harvest_results(preview, dry_run=True)
+    applicable = sum(1 for r in preview if r.status.value == "applied")
+    if applicable == 0:
+        return
+    if click.confirm(f"Apply {applicable} patch(es)?"):
+        results = apply_patches(patches, resolved_dir)
+        render_harvest_results(results)

cctx/diagnostician/__init__.py

@@ -0,0 +1,81 @@
+"""Autopsy diagnostician — public entry point.
+
+run(trace) -> Diagnosis
+  Runs all three pattern classifiers, detects inflection turn,
+  patches cost attribution for stale_context findings, and returns
+  a Diagnosis with patches=[].
+
+The Recommender (cctx.recommender.claude_md) populates patches.
+"""
+from __future__ import annotations
+
+import dataclasses
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from cctx.diagnostician import inflection
+from cctx.diagnostician.patterns import retry_loop, scope_creep, stale_context
+from cctx.models import Diagnosis, Finding, FindingKind
+from cctx.pricing import price_per_tok as _price_per_tok
+
+if TYPE_CHECKING:
+    from cctx.models import SessionTrace
+
+UTC = timezone.utc
+
+
+def _patch_costs(findings: list[Finding], model: str | None) -> list[Finding]:
+    price = _price_per_tok(model)
+    result = []
+    for f in findings:
+        if f.kind is FindingKind.STALE_CONTEXT:
+            tt = f.evidence.get("total_token_turns", 0)
+            f = dataclasses.replace(f, cost_usd=round(tt * price, 4))
+        result.append(f)
+    return result
+
+
+def _compute_total_cost(trace: SessionTrace, model: str | None) -> float:
+    """Approximate total session cost including cache reads and writes.
+
+    Billing rates relative to base input price:
+      cache_read:  ×0.10  (read from prompt cache)
+      cache_write: ×1.25  (write to prompt cache, both 5-min and 1-hr TTLs)
+    """
+    price = _price_per_tok(model)
+    total = 0.0
+    for turn in trace.turns:
+        if turn.usage is not None:
+            total += turn.usage.input_tokens * price
+            total += turn.usage.cache_read * price * 0.1
+            cache_writes = turn.usage.cache_creation_5m + turn.usage.cache_creation_1h
+            total += cache_writes * price * 1.25
+    return round(total, 4)
+
+
+def run(trace: SessionTrace) -> Diagnosis:
+    """Diagnose a single SessionTrace. Returns Diagnosis with patches=[]."""
+    findings: list[Finding] = [
+        *retry_loop.classify(trace),
+        *scope_creep.classify(trace),
+        *stale_context.classify(trace),
+    ]
+    findings.sort(key=lambda f: f.first_turn)
+
+    inflection_turn = inflection.detect(findings)
+    findings = _patch_costs(findings, trace.primary_model)
+
+    total_cost = _compute_total_cost(trace, trace.primary_model)
+    waste_cost = sum(f.cost_usd for f in findings if f.cost_usd is not None)
+    # Waste cannot exceed total session cost — cap as a logical invariant.
+    waste_cost = min(waste_cost, total_cost)
+
+    return Diagnosis(
+        session_id=trace.session_id,
+        findings=findings,
+        inflection_turn=inflection_turn,
+        patches=[],
+        total_cost_usd=total_cost,
+        waste_cost_usd=round(waste_cost, 4),
+        analysed_at=datetime.now(UTC),
+    )

cctx/diagnostician/aggregate.py

@@ -0,0 +1,40 @@
+"""Cross-session aggregator.
+
+run(project_dir, window) -> list[Diagnosis]
+
+Discovers session JSONL files in project_dir modified within the time window,
+parses each one, runs the per-session diagnostician, and returns the list of
+Diagnoses. The CLI orchestrates the recommender call separately.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from cctx import diagnostician
+from cctx.parsers.claude_code import parse_session
+from cctx.tokenizer import tokenize_session
+
+if TYPE_CHECKING:
+    from cctx.models import Diagnosis
+
+UTC = timezone.utc
+
+
+def run(project_dir: Path, window: timedelta) -> list[Diagnosis]:
+    cutoff = datetime.now(UTC) - window
+    paths = sorted(project_dir.glob("*.jsonl"), key=lambda p: p.stat().st_mtime)
+
+    result = []
+    for path in paths:
+        mtime = datetime.fromtimestamp(path.stat().st_mtime, UTC)
+        if mtime < cutoff:
+            continue
+        try:
+            trace = tokenize_session(parse_session(path))
+            diagnosis = diagnostician.run(trace)
+            result.append(diagnosis)
+        except Exception:
+            continue  # skip corrupt sessions; don't fail the whole run
+    return result

cctx/diagnostician/inflection.py

@@ -0,0 +1,19 @@
+"""Inflection-turn detection.
+
+The inflection turn is the earliest turn in the session where a classifier
+found a problem. Future versions may detect inflection from turn-level signals
+that precede any classifier finding (rising error rate, apology language, etc.).
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cctx.models import Finding
+
+
+def detect(findings: list[Finding]) -> int | None:
+    """Return the earliest first_turn across all findings, or None."""
+    if not findings:
+        return None
+    return min(f.first_turn for f in findings)

cctx/diagnostician/patterns/__init__.py

@@ -0,0 +1 @@
+"""Pattern classifiers."""

cctx/diagnostician/patterns/retry_loop.py

@@ -0,0 +1,145 @@
+"""Retry-loop classifier.
+
+Detects repeated identical-failing tool calls with no intervening successful
+fix. One Finding per session — all loops bundled into a single Finding with
+all occurrences in evidence.
+"""
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+from cctx.models import Confidence, Finding, FindingKind, Severity
+
+if TYPE_CHECKING:
+    from cctx.models import SessionTrace, ToolResult
+
+
+def _similarity_key(tool_name: str, tool_input: dict) -> str:
+    match tool_name:
+        case "Bash":
+            return tool_input.get("command", "").strip()
+        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 _classify_impl(trace: SessionTrace) -> list[Finding]:
+    # Build tool_use_id → (ToolResult, turn_number) map
+    result_map: dict[str, tuple[ToolResult, int]] = {}
+    for turn in trace.turns:
+        for tr in turn.tool_results:
+            result_map[tr.tool_use_id] = (tr, turn.turn_number)
+
+    # Collect all tool calls with their error status
+    # Each entry: (tool_name, key, turn_number, is_error, tool_use_id)
+    Record = tuple[str, str, int, bool, str]
+    records: list[Record] = []
+    for turn in trace.turns:
+        if turn.role != "assistant":
+            continue
+        for tu in turn.tool_uses:
+            pair = result_map.get(tu.tool_use_id)
+            if pair is None:
+                continue
+            result, _ = pair
+            key = _similarity_key(tu.tool_name, tu.tool_input)
+            records.append((tu.tool_name, key, turn.turn_number, _is_error(result), tu.tool_use_id))
+
+    # Group by (tool_name, key)
+    groups: dict[tuple[str, str], list[Record]] = defaultdict(list)
+    for rec in records:
+        groups[(rec[0], rec[1])].append(rec)
+
+    loop_occurrences: list[dict] = []
+
+    for (tool_name, key), group in groups.items():
+        error_recs = [r for r in group if r[3]]
+        if len(error_recs) < 2:
+            continue
+
+        first_err_turn = error_recs[0][2]
+        last_err_turn = error_recs[-1][2]
+
+        # Check for any successful call between the first and last error
+        intervening_success = any(
+            r for r in group
+            if not r[3] and first_err_turn < r[2] < last_err_turn
+        )
+        if intervening_success:
+            continue
+
+        loop_occurrences.append({
+            "tool_name": tool_name,
+            "key": key,
+            "error_recs": error_recs,
+        })
+
+    if not loop_occurrences:
+        return []
+
+    # Flatten all error records and build evidence
+    all_errors: list[Record] = sorted(
+        (r for occ in loop_occurrences for r in occ["error_recs"]),
+        key=lambda r: r[2],
+    )
+
+    loop_length = len(all_errors)
+    # first_turn = turn of the second failing call (loop established here)
+    second_errors = []
+    for occ in loop_occurrences:
+        if len(occ["error_recs"]) >= 2:
+            second_errors.append(occ["error_recs"][1][2])
+    first_turn = min(second_errors)
+    last_turn = max(r[2] for r in all_errors)
+
+    severity = Severity.HIGH if loop_length >= 4 else Severity.MEDIUM
+
+    evidence_occurrences = []
+    for r in all_errors:
+        result, _ = result_map[r[4]]
+        evidence_occurrences.append({
+            "turn": r[2],
+            "key": r[1],
+            "call": r[0],
+            "error": result.content[:120],
+        })
+
+    # Summary: describe the first loop
+    first_occ = loop_occurrences[0]
+    first_err = first_occ["error_recs"]
+    tool_label = f"{first_occ['tool_name']}({first_occ['key'][:40]})"
+    summary = f"{tool_label} failed {loop_length}× between turns {first_err[0][2]}–{last_turn}"
+
+    return [Finding(
+        kind=FindingKind.RETRY_LOOP,
+        severity=severity,
+        confidence=Confidence.HIGH,
+        first_turn=first_turn,
+        last_turn=last_turn,
+        evidence={"occurrences": evidence_occurrences, "loop_length": loop_length},
+        cost_usd=None,
+        summary=summary,
+    )]
+
+
+def classify(trace: SessionTrace) -> list[Finding]:
+    try:
+        return _classify_impl(trace)
+    except Exception:
+        return []