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

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

@@ -2,6 +2,57 @@
 
 <!-- version list -->
 
+## v1.5.1 (2026-06-10)
+
+### Bug Fixes
+
+- Recommender — add TOOL_THRASH/DEAD_END patch templates
+  ([#107](https://github.com/jacquardlabs/cctx/pull/107),
+  [`3c79d58`](https://github.com/jacquardlabs/cctx/commit/3c79d58a55af106d3fd81542e70b8f892569185c))
+
+### Documentation
+
+- Product review 2026-06-09 + M15 cross-agent emit spec
+  ([#107](https://github.com/jacquardlabs/cctx/pull/107),
+  [`3c79d58`](https://github.com/jacquardlabs/cctx/commit/3c79d58a55af106d3fd81542e70b8f892569185c))
+
+
+## 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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.4.0
+Version: 1.5.1
 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.1}/PRODUCT.md

@@ -4,7 +4,7 @@
 
 cctx is a local Python CLI that reads Claude Code session logs and tells you what went wrong, why it cost what it did, and what to add to your CLAUDE.md so it doesn't happen again.
 
-It is a forensic tool, not a monitoring tool. You reach for it after a session — when something felt off, when the bill was higher than expected, or on a weekly review pass.
+It is forensic-first. You reach for it after a session — when something felt off, when the bill was higher than expected, or on a weekly review pass. `cctx watch` extends the same waste detection into a live, opt-in companion for an active session; it is a foreground command you run deliberately, not background infrastructure.
 
 ## Primary persona
 
@@ -20,7 +20,7 @@ This persona is already the target; everything shipped to date serves them direc
 ## What cctx is NOT for
 
 - Teams or organizations (no shared reports, no access control, no multi-user state)
-- Real-time monitoring (completed sessions only in v0 and v1)
+- Ambient monitoring (no daemons, no persistent watcher state, no alerting — `cctx watch` is a foreground command you start and stop)
 - General cost dashboards (CodeBurn covers that; cctx is forensic)
 - Multi-provider support (Claude Code only in v0/v1)
 - Users who do not read session transcripts or maintain CLAUDE.md
@@ -28,7 +28,7 @@ This persona is already the target; everything shipped to date serves them direc
 ## Product principles
 
 **1. Forensic, not ambient.**
-cctx is used after something goes wrong, not as background infrastructure. Every feature should be justified by this use case: "I just ran a session, something went sideways, I want to know what."
+cctx is forensic-first: the core use case is "I just ran a session, something went sideways, I want to know what." Live mode (`watch`) is justified only as the same detection running earlier — it surfaces the identical findings, never becomes a daemon, and never holds state between runs.
 
 **2. Output must be actionable.**
 Every report should produce at least one thing the user can do immediately. Findings without patches are incomplete. Patches must be copy-pasteable or auto-applicable.
@@ -37,15 +37,15 @@ Every report should produce at least one thing the user can do immediately. Find
 Costs are approximated (85–95% of actual). Pattern classifiers fire only on high-confidence signals. Low-confidence signals are shown with explicit confidence labels. "System internals" token budget is never hidden or misattributed.
 
 **4. Local and stateless.**
-No network calls in the core analysis path (tokenizer may call the API for token counting; that is opt-in). No persistent database. No telemetry. No account. Users own their data.
+No network calls in the core analysis path (tokenizer may call the API for token counting; that is opt-in). Live-session detection may shell out to the local `claude` CLI and degrades gracefully without it. No persistent database. No telemetry. No account. Users own their data.
 
 **5. Deterministic.**
 Pattern classifiers are heuristics, not LLM calls. The same session file produces the same output every time. Testable on fixtures. Predictable cost to run.
 
 **6. Small surface, deep on each command.**
-Four commands. No command is shallow. Users should be able to learn the product in an afternoon and trust what it tells them.
+Six commands (`ls`, `autopsy`, `harvest`, `watch`, `trace`, `export`). No command is shallow. Users should be able to learn the product in an afternoon and trust what it tells them.
 
-## Feature map (v0.2.0)
+## Feature map (v1.4.0)
 
 ### Shipped
 
@@ -68,8 +68,16 @@ Four commands. No command is shallow. Users should be able to learn the product
 | Cross-session harvest | `cctx harvest <project> --since N` | M5 |
 | Session discovery | `cctx ls` / `cctx autopsy --latest` | M6+ |
 | Live waste signals | `cctx watch <project>` | M6+ |
+| Verdict headline + `--top N` + `--turn N` | `autopsy` | v1.1.0 (M9) |
+| `--until DATE` on cross-session mode | `autopsy --since ... --until` | v1.2.0 (M12) |
+| Machine-readable diagnosis | `cctx autopsy <session> --json` | v1.2.0 (M12) |
+| JSON export | `cctx export <session> --format json` | v1.2.0 (M12) |
+| Project-specific pattern detection | `autopsy`/`harvest` `--since` | v1.3.0 (M14) |
+| Memory-hygiene depth | `harvest --check` + `--check-severity` | v1.4.0 (M13) |
+| Live session badges | `cctx ls` | unreleased |
+| Live session detection, early idle exit | `cctx watch` | unreleased |
 
-### Pattern classifiers (v0.2.0)
+### Pattern classifiers (v1.4.0)
 
 | Pattern | Status |
 |---|---|
@@ -78,6 +86,7 @@ Four commands. No command is shallow. Users should be able to learn the product
 | Stale context | Shipped |
 | Dead-end exploration | Shipped (v0.2.0) |
 | Tool thrashing | Shipped (v0.2.0) |
+| Project-specific patterns (cross-session) | Shipped (v1.3.0) |
 
 ## What we are NOT building
 
@@ -87,12 +96,14 @@ Four commands. No command is shallow. Users should be able to learn the product
 - A fork-and-replay debugger
 - A general eval or testing framework
 
-## Known problems (as of 2026-05-16)
+## Known problems (as of 2026-06-09)
 
-**Active gaps (non-blocking for v0.2.0 but worth tracking):**
+**Active gaps:**
 
-1. **`cctx watch` polling is simple.** Polls every 1s and re-runs classifiers on any file growth. Does not debounce or use `fsevents`/`inotify`. Fine for v0 but will chatter on active sessions.
+1. **`cctx watch` polling is simple.** Early idle exit via `claude agents --json` has landed, but the watcher still polls at 1s without `fsevents`/`inotify` debouncing.
 
-2. **`--format json` on `export` not shipped.** `--html` moved to `autopsy --html`; `json` format on the `export` subcommand is still deferred.
+2. **Subagent traces are parsed but never diagnosed.** The parser models subagent sessions recursively and the tokenizer counts their tokens, but no classifier or cost attribution reads `trace.subagents`. Autopsy is blind to spend inside agent fan-outs. (M16)
 
-3. **Cross-agent layer not started.** Emitting findings as `.cursorrules`, `AGENTS.md`, `.windsurfrules`, or GitHub Copilot instructions is a roadmap item with no milestone yet.
+3. **Cross-agent layer not started.** Tracked as M15 / #82 — the final step of the original growth staircase.
+
+4. **Harvest has no feedback loop.** Nothing measures whether an applied patch reduced the recurrence of the pattern it targeted, even though patches carry fingerprints and sessions carry dates. (M17)

{cctx_cli-1.4.0 → cctx_cli-1.5.1}/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.1"

cctx_cli-1.5.1/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.1}/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.1}/cctx/recommender/claude_md.py

@@ -41,11 +41,29 @@ _STALE_CONTEXT_DIFF = """\
 +without re-referencing it. Prefer re-running the tool over dragging stale context
 +forward — the compaction system handles removal."""
 
+_TOOL_THRASH_DIFF = """\
++## Tool-call discipline
++
++Before reaching for a tool, decide what specific information the call must return
++and how it changes the next step. Don't fan out near-identical searches or re-read
++the same file from different angles hoping something turns up. If two or three calls
++haven't moved you forward, stop and form a hypothesis before the next one."""
+
+_DEAD_END_DIFF = """\
++## Exploration discipline
++
++When an approach stops making progress, name the dead end explicitly and back out
++rather than pushing deeper on a path that isn't working. Re-read the goal, list the
++approaches already ruled out, and pick a meaningfully different one. Sunk effort on a
++failing approach is not a reason to continue it."""
+
 _TEMPLATES: dict[FindingKind, tuple[str, str, str]] = {
     # kind → (description, diff_body, target_file)
-    FindingKind.RETRY_LOOP:    ("Add retry discipline rule",    _RETRY_LOOP_DIFF,    "CLAUDE.md"),
-    FindingKind.SCOPE_CREEP:   ("Add scope discipline rule",    _SCOPE_CREEP_DIFF,   "CLAUDE.md"),
-    FindingKind.STALE_CONTEXT: ("Add context hygiene rule",     _STALE_CONTEXT_DIFF, "CLAUDE.md"),
+    FindingKind.RETRY_LOOP:    ("Add retry discipline rule", _RETRY_LOOP_DIFF, "CLAUDE.md"),
+    FindingKind.SCOPE_CREEP:   ("Add scope discipline rule", _SCOPE_CREEP_DIFF, "CLAUDE.md"),
+    FindingKind.STALE_CONTEXT: ("Add context hygiene rule", _STALE_CONTEXT_DIFF, "CLAUDE.md"),
+    FindingKind.TOOL_THRASH:   ("Add tool-call discipline rule", _TOOL_THRASH_DIFF, "CLAUDE.md"),
+    FindingKind.DEAD_END:      ("Add exploration discipline rule", _DEAD_END_DIFF, "CLAUDE.md"),
 }
 
 

{cctx_cli-1.4.0 → cctx_cli-1.5.1}/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.1}/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)