cctx-cli 1.4.0__tar.gz → 1.5.0__tar.gz

{cctx_cli-1.4.0 → cctx_cli-1.5.0}/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 <!-- version list -->
 
+## v1.5.0 (2026-05-20)
+
+### Bug Fixes
+
+- Agents.py — guard against non-list JSON, tighten patch targets
+  ([`c41c42c`](https://github.com/jacquardlabs/cctx/commit/c41c42cb366904fc332638b8f97ee042f17b45c2))
+
+- Renderer — guard order, tmp_path fixtures, missing no-badge tests
+  ([`8f26afd`](https://github.com/jacquardlabs/cctx/commit/8f26afdf27c63641942b434e47a2fb7b24d38068))
+
+- Watcher — hermetic tests, reuse _encode_path, rename clarity
+  ([`a7b52de`](https://github.com/jacquardlabs/cctx/commit/a7b52def47b13447d956476a0ec6782fe2d0247b))
+
+### Documentation
+
+- Implementation plan for claude agents live integration
+  ([`2136adf`](https://github.com/jacquardlabs/cctx/commit/2136adf0697a695d27f438f0368e7bd5ba406e89))
+
+- Spec for claude agents --json live session integration
+  ([`0df2381`](https://github.com/jacquardlabs/cctx/commit/0df23813a90c66e57d0d39c6b959859b89a5c057))
+
+### Features
+
+- Add agents.py — live_sessions() via claude agents --json
+  ([`83b704f`](https://github.com/jacquardlabs/cctx/commit/83b704ffbe4303dbd316257a01eb0b59307c0e06))
+
+- Cctx ls — pass live_statuses to renderer for live session badges
+  ([`65445d7`](https://github.com/jacquardlabs/cctx/commit/65445d75a213bf26401fe044a2409d2ce0efbcb1))
+
+- Render_sessions/render_projects — live status badges via live_statuses param
+  ([`3d77687`](https://github.com/jacquardlabs/cctx/commit/3d776879c9ce03a622361c2b804e5986d40f37a1))
+
+- Watcher — live session detection + early idle exit via claude agents --json
+  ([`a11481c`](https://github.com/jacquardlabs/cctx/commit/a11481c2126fead87e1f92bfecc7bf5ac3f39d1a))
+
+
 ## v1.4.0 (2026-05-20)
 
 ### Bug Fixes

{cctx_cli-1.4.0 → cctx_cli-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.4.0
+Version: 1.5.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.4.0 → cctx_cli-1.5.0}/cctx/__init__.py

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

cctx_cli-1.5.0/cctx/agents.py

@@ -0,0 +1,66 @@
+"""Live Claude Code agent query via `claude agents --json`.
+
+Public API:
+    live_sessions() -> list[LiveSession]
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+
+@dataclass
+class LiveSession:
+    session_id: str    # matches JSONL filename stem in ~/.claude/projects/
+    cwd: str
+    status: str        # "busy" | "idle"
+    pid: int
+    kind: str          # "interactive" | "background"
+    started_at: datetime
+
+
+def live_sessions() -> list[LiveSession]:
+    """Query `claude agents --json`. Returns [] on any failure."""
+    try:
+        result = subprocess.run(
+            ["claude", "agents", "--json"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+        )
+    except FileNotFoundError:
+        return []
+    except subprocess.TimeoutExpired:
+        return []
+
+    if result.returncode != 0:
+        return []
+
+    try:
+        data = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return []
+
+    if not isinstance(data, list):
+        return []
+
+    sessions: list[LiveSession] = []
+    for item in data:
+        try:
+            sessions.append(
+                LiveSession(
+                    session_id=item["sessionId"],
+                    cwd=item["cwd"],
+                    status=item.get("status", "unknown"),
+                    pid=int(item["pid"]),
+                    kind=item.get("kind", "interactive"),
+                    started_at=datetime.fromtimestamp(
+                        item["startedAt"] / 1000, tz=timezone.utc
+                    ),
+                )
+            )
+        except (KeyError, TypeError, ValueError):
+            continue
+    return sessions

{cctx_cli-1.4.0 → cctx_cli-1.5.0}/cctx/cli.py

@@ -19,6 +19,7 @@ from typing import IO
 import rich_click as click
 
 from cctx import diagnostician
+from cctx.agents import live_sessions as _live_sessions
 from cctx.diagnostician import aggregate
 from cctx.diagnostician.patterns import project_specific
 from cctx.discovery import complete_project as _complete_project
@@ -196,9 +197,11 @@ def ls(project: Path | None) -> None:
     """
     from cctx.discovery import ProjectInfo, find_project_dir, list_projects, list_sessions
 
+    live_statuses = {s.session_id: s.status for s in _live_sessions()}
+
     if project is None:
         projects = list_projects()
-        render_projects(projects)
+        render_projects(projects, live_statuses=live_statuses)
     else:
         cwd = project if project.is_dir() else project.parent
         project_dir = find_project_dir(cwd)
@@ -213,7 +216,7 @@ def ls(project: Path | None) -> None:
             display_name=str(cwd).replace(str(Path.home()), "~"),
             sessions=sessions,
         )
-        render_sessions(info)
+        render_sessions(info, live_statuses=live_statuses)
 
 
 @cli.command()

{cctx_cli-1.4.0 → cctx_cli-1.5.0}/cctx/renderers/terminal.py

@@ -3,8 +3,8 @@
 render_diagnosis(diagnosis, console=None) -> None
 render_aggregate(report, console=None) -> None
 render_harvest_results(results, dry_run=False, console=None) -> None
-render_projects(projects, console=None) -> None
-render_sessions(project, console=None) -> None
+render_projects(projects, live_statuses=None, console=None) -> None
+render_sessions(project, live_statuses=None, console=None) -> None
 
 Uses rich for formatting. Accepts an optional Console for testing.
 """
@@ -294,25 +294,44 @@ def render_harvest_results(
         con.print(f"Applied {applied_count} patch(es).")
 
 
-def render_projects(projects: list[ProjectInfo], *, console: Console | None = None) -> None:
+def render_projects(
+    projects: list[ProjectInfo],
+    *,
+    live_statuses: dict[str, str] | None = None,
+    console: Console | None = None,
+) -> None:
     con = console or _default_console()
 
     if not projects:
         con.print("No projects found in ~/.claude/projects/.")
         return
 
+    _live = live_statuses or {}
+    live_project_ids: set[str] = {
+        proj.project_dir.name
+        for proj in projects
+        for s in proj.sessions
+        if s.session_id in _live
+    }
+
     con.print(Rule("cctx — projects"))
     table = Table(show_header=True, box=None, pad_edge=False, show_edge=False)
     table.add_column("Project", style="bold")
     table.add_column("Sessions", justify="right", style="dim")
     table.add_column("Last session", style="dim")
+    table.add_column("Status")
 
     for proj in projects:
         last = proj.latest_time.strftime("%Y-%m-%d") if proj.latest_time else "—"
+        if proj.project_dir.name in live_project_ids:
+            status_cell = Text("● live", style="green bold")
+        else:
+            status_cell = Text("")
         table.add_row(
             proj.display_name,
             str(proj.session_count),
             last,
+            status_cell,
         )
     con.print(table)
     con.print()
@@ -326,8 +345,14 @@ def render_projects(projects: list[ProjectInfo], *, console: Console | None = No
     )
 
 
-def render_sessions(project: ProjectInfo, *, console: Console | None = None) -> None:
+def render_sessions(
+    project: ProjectInfo,
+    *,
+    live_statuses: dict[str, str] | None = None,
+    console: Console | None = None,
+) -> None:
     con = console or _default_console()
+    _live = live_statuses or {}
 
     con.print(Rule(f"cctx — {project.display_name}"))
     if not project.sessions:
@@ -339,14 +364,20 @@ def render_sessions(project: ProjectInfo, *, console: Console | None = None) ->
     table.add_column("Date", style="dim")
     table.add_column("Branch", style="dim")
     table.add_column("Path", style="dim")
+    table.add_column("Status")
 
     for s in project.sessions:
         date_str = s.start_time.strftime("%Y-%m-%d %H:%M") if s.start_time else "—"
+        if s.session_id in _live:
+            status_cell = Text(f"● {_live[s.session_id]}", style="green bold")
+        else:
+            status_cell = Text("")
         table.add_row(
             s.session_id[:8],
             date_str,
             s.git_branch or "—",
             str(s.path),
+            status_cell,
         )
     con.print(table)
     con.print()

{cctx_cli-1.4.0 → cctx_cli-1.5.0}/cctx/watcher.py

@@ -4,7 +4,7 @@ Public API:
     watch(target) -> None
 
 Layering rules (MUST respect):
-- Imports parser and diagnostician only.
+- Imports parser, diagnostician, and agents only.
 - Does NOT import renderers, click, rich, or anthropic.
 - Uses a compact single-line formatter defined here (not imported from renderers).
 """
@@ -16,6 +16,7 @@ import time
 from pathlib import Path
 
 from cctx import diagnostician
+from cctx.agents import live_sessions
 from cctx.models import KIND_LABEL, Finding, FindingKind
 
 _POLL_INTERVAL = 1.0    # seconds between size checks
@@ -34,11 +35,22 @@ def _format_finding(f: Finding) -> str:
 
 
 def _find_active_session(project_dir: Path) -> Path | None:
-    """Return the most recently modified JSONL in project_dir, or None.
+    """Return the JSONL for the active session in project_dir.
 
-    Uses st_mtime (not embedded session start_time) so that a currently-active
-    session sorts above older completed sessions regardless of their timestamps.
+    Prefers the live session from `claude agents --json` when available;
+    falls back to most-recently-modified JSONL.
     """
+    from cctx.discovery import _encode_path
+
+    encoded_name = project_dir.name
+    for live in live_sessions():
+        if live.cwd:
+            live_encoded = _encode_path(Path(live.cwd))
+            if live_encoded == encoded_name:
+                candidate = project_dir / f"{live.session_id}.jsonl"
+                if candidate.exists():
+                    return candidate
+
     candidates = list(project_dir.glob("*.jsonl"))
     if not candidates:
         return None
@@ -69,6 +81,8 @@ def _tail(session_path: Path) -> int:
     seen_keys: set[tuple[FindingKind, int]] = set()
     last_size = 0
     idle_since: float | None = None
+    session_id = session_path.stem
+    claude_is_responsive = False  # True once we've confirmed claude is available
 
     print(f"Watching {session_path.name} …  Ctrl+C to stop.", flush=True)
 
@@ -99,13 +113,25 @@ def _tail(session_path: Path) -> int:
             now = time.monotonic()
             if idle_since is None:
                 idle_since = now
-            elif now - idle_since >= _IDLE_TIMEOUT:
-                print(
-                    f"\nSession idle for {_IDLE_TIMEOUT:.0f}s — analysis complete. "
-                    f"Findings detected: {len(seen_keys)}",
-                    flush=True,
-                )
-                return len(seen_keys)
+            else:
+                live = live_sessions()
+                live_ids = {s.session_id for s in live}
+                if live:
+                    claude_is_responsive = True
+                if claude_is_responsive and session_id not in live_ids:
+                    print(
+                        f"\nSession ended — analysis complete. "
+                        f"Findings detected: {len(seen_keys)}",
+                        flush=True,
+                    )
+                    return len(seen_keys)
+                if now - idle_since >= _IDLE_TIMEOUT:
+                    print(
+                        f"\nSession idle for {_IDLE_TIMEOUT:.0f}s — analysis complete. "
+                        f"Findings detected: {len(seen_keys)}",
+                        flush=True,
+                    )
+                    return len(seen_keys)
 
         time.sleep(_POLL_INTERVAL)