sessionpulse 0.1.0__py3-none-any.whl

sessionpulse/install.py

@@ -0,0 +1,149 @@
+"""Adds and removes Session Pulse's hooks in Claude Code's settings.json,
+and its login autostart entry.
+
+Our hook entries are recognised by HOOK_MARK in the command, so install is
+idempotent (re-running updates the interpreter path) and uninstall removes
+only what we added. settings.json is backed up before every change and
+written atomically; if it isn't valid JSON we refuse to touch it.
+"""
+import json
+import os
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .config import Config
+
+HOOK_MARK = "-m sessionpulse hook"
+EVENTS = ("SessionStart", "SessionEnd")
+AUTOSTART = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "autostart" / "sessionpulse.desktop"
+
+
+class SettingsError(Exception):
+    pass
+
+
+def hook_command():
+    return f'"{sys.executable}" {HOOK_MARK}'
+
+
+def _settings_path(cfg: Config) -> Path:
+    return cfg.claude / "settings.json"
+
+
+def _load(path: Path):
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text())
+    except ValueError as exc:
+        raise SettingsError(f"{path} is not valid JSON ({exc}); not changing it.") from exc
+    if not isinstance(data, dict):
+        raise SettingsError(f"{path} is not a JSON object; not changing it.")
+    return data
+
+
+def _save(path: Path, data):
+    if path.exists():
+        stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+        shutil.copy2(path, path.with_name(f"{path.name}.sessionpulse-backup-{stamp}"))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".sessionpulse-tmp")
+    tmp.write_text(json.dumps(data, indent=2) + "\n")
+    os.replace(tmp, path)
+
+
+def _ours(hook):
+    return isinstance(hook, dict) and HOOK_MARK in str(hook.get("command", ""))
+
+
+def hooks_installed(cfg: Config):
+    data = _load(_settings_path(cfg))
+    found = set()
+    for ev in EVENTS:
+        for group in (data.get("hooks") or {}).get(ev) or []:
+            if any(_ours(h) for h in (group or {}).get("hooks") or []):
+                found.add(ev)
+    return found
+
+
+def install_hooks(cfg: Config):
+    path = _settings_path(cfg)
+    data = _load(path)
+    hooks = data.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        raise SettingsError(f'"hooks" in {path} is not an object; not changing it.')
+    ours = {"type": "command", "command": hook_command(), "timeout": 10}
+    changed = False
+    for ev in EVENTS:
+        groups = hooks.setdefault(ev, [])
+        present = False
+        for group in groups:
+            for i, h in enumerate((group or {}).get("hooks") or []):
+                if _ours(h):
+                    present = True
+                    if h != ours:
+                        group["hooks"][i] = dict(ours)
+                        changed = True
+        if not present:
+            groups.append({"hooks": [dict(ours)]})
+            changed = True
+    if changed:
+        _save(path, data)
+    return changed
+
+
+def uninstall_hooks(cfg: Config):
+    path = _settings_path(cfg)
+    data = _load(path)
+    hooks = data.get("hooks")
+    if not isinstance(hooks, dict):
+        return False
+    changed = False
+    for ev in EVENTS:
+        groups = hooks.get(ev)
+        if not isinstance(groups, list):
+            continue
+        kept = []
+        for group in groups:
+            inner = (group or {}).get("hooks") or []
+            left = [h for h in inner if not _ours(h)]
+            if len(left) != len(inner):
+                changed = True
+                if not left:
+                    continue
+                group = {**group, "hooks": left}
+            kept.append(group)
+        if kept:
+            hooks[ev] = kept
+        else:
+            del hooks[ev]
+    if not hooks:
+        data.pop("hooks")
+    if changed:
+        _save(path, data)
+    return changed
+
+
+def enable_autostart():
+    icon = Path(__file__).with_name("icons") / "sessionpulse-idle.svg"
+    AUTOSTART.parent.mkdir(parents=True, exist_ok=True)
+    AUTOSTART.write_text(
+        "[Desktop Entry]\n"
+        "Type=Application\n"
+        "Name=Session Pulse\n"
+        "Comment=Panel icon and dashboard for Claude Code sessions\n"
+        f'Exec="{sys.executable}" -m sessionpulse tray\n'
+        f"Icon={icon}\n"
+        "Terminal=false\n"
+        "X-GNOME-Autostart-enabled=true\n"
+        "X-GNOME-Autostart-Delay=5\n")
+    return AUTOSTART
+
+
+def disable_autostart():
+    if AUTOSTART.exists():
+        AUTOSTART.unlink()
+        return True
+    return False

sessionpulse/learn.py

@@ -0,0 +1,158 @@
+"""The dashboard's "Get better at Claude Code" section.
+
+LIBRARY is a short, hand-checked list of free, official places to learn.
+suggest() looks at your own sessions and puts the most relevant items first,
+with the reason taken from your data ("9 sessions ran past 40 prompts").
+It only reads what the reader already parsed, plus whether CLAUDE.md exists in
+your busiest project folders and whether settings.json has hooks of your own.
+"""
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+
+DOCS = "https://code.claude.com/docs/en/"
+
+# level: start = new to Claude Code, better = using it daily, advanced = extending it.
+LIBRARY = [
+    {"id": "quickstart", "level": "start", "kind": "Docs", "title": "Quickstart",
+     "url": DOCS + "quickstart", "blurb": "Your first real task, step by step."},
+    {"id": "course-cc", "level": "better", "kind": "Course",
+     "title": "Claude Code in Action (Anthropic Academy)",
+     "url": "https://anthropic.skilljar.com/claude-code-in-action",
+     "blurb": "Free course for daily users: long sessions, CLAUDE.md and skills, automating repeat work."},
+    {"id": "best-practices", "level": "start", "kind": "Docs", "title": "Best practices for Claude Code",
+     "url": DOCS + "best-practices", "blurb": "How to give context, check work and keep sessions on track."},
+    {"id": "workflows", "level": "start", "kind": "Docs", "title": "Common workflows",
+     "url": DOCS + "common-workflows", "blurb": "Recipes: understand a codebase, fix bugs, refactor, write tests, open PRs."},
+    {"id": "eng-blog", "level": "better", "kind": "Article", "title": "Claude Code: best practices for agentic coding",
+     "url": "https://www.anthropic.com/engineering/claude-code-best-practices",
+     "blurb": "Anthropic's engineers on the habits that work: explore, plan, code, commit."},
+    {"id": "memory", "level": "better", "kind": "Docs", "title": "How Claude remembers your project (CLAUDE.md)",
+     "url": DOCS + "memory", "blurb": "Write project instructions once instead of repeating them every session."},
+    {"id": "context", "level": "better", "kind": "Docs", "title": "Explore the context window",
+     "url": DOCS + "context-window", "blurb": "What fills the context, and when to /clear or /compact."},
+    {"id": "costs", "level": "better", "kind": "Docs", "title": "Manage costs effectively",
+     "url": DOCS + "costs", "blurb": "Keep token use down without slowing yourself down."},
+    {"id": "plan-mode", "level": "better", "kind": "Docs", "title": "Permission modes, including plan mode",
+     "url": DOCS + "permission-modes", "blurb": "Have Claude plan and agree the approach before it edits anything."},
+    {"id": "prompting", "level": "better", "kind": "Docs", "title": "Prompt engineering overview",
+     "url": "https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview",
+     "blurb": "Be clear and specific, give examples, say what done looks like."},
+    {"id": "prompt-tutorial", "level": "better", "kind": "Tutorial", "title": "Interactive prompt engineering tutorial",
+     "url": "https://github.com/anthropics/prompt-eng-interactive-tutorial",
+     "blurb": "Nine hands-on chapters with exercises, from Anthropic."},
+    {"id": "subagents", "level": "advanced", "kind": "Docs", "title": "Create custom subagents",
+     "url": DOCS + "sub-agents", "blurb": "Hand research or review to a helper with its own context."},
+    {"id": "skills", "level": "advanced", "kind": "Docs", "title": "Extend Claude with skills",
+     "url": DOCS + "skills", "blurb": "Package a procedure you repeat so Claude follows it the same way every time."},
+    {"id": "course-skills", "level": "advanced", "kind": "Course",
+     "title": "Introduction to agent skills (Anthropic Academy)",
+     "url": "https://anthropic.skilljar.com/introduction-to-agent-skills",
+     "blurb": "Free course on writing and using skills."},
+    {"id": "mcp", "level": "advanced", "kind": "Docs", "title": "Connect Claude Code to tools via MCP",
+     "url": DOCS + "mcp", "blurb": "Let Claude use your issue tracker, database, browser or chat."},
+    {"id": "course-mcp", "level": "advanced", "kind": "Course",
+     "title": "Introduction to Model Context Protocol (Anthropic Academy)",
+     "url": "https://anthropic.skilljar.com/introduction-to-model-context-protocol",
+     "blurb": "Free course: how MCP servers work and how to build one."},
+    {"id": "hooks", "level": "advanced", "kind": "Docs", "title": "Automate actions with hooks",
+     "url": DOCS + "hooks-guide", "blurb": "Run formatters, checks or notifications automatically at set points."},
+    {"id": "worktrees", "level": "advanced", "kind": "Docs", "title": "Run parallel sessions with worktrees",
+     "url": DOCS + "worktrees", "blurb": "Work on several tasks at once without them touching each other."},
+    {"id": "headless", "level": "advanced", "kind": "Docs", "title": "Run Claude Code programmatically",
+     "url": DOCS + "headless", "blurb": "Use Claude Code from scripts, cron and CI."},
+    {"id": "whats-new", "level": "current", "kind": "Docs", "title": "What's new (weekly)",
+     "url": DOCS + "whats-new", "blurb": "A short weekly note on new features."},
+    {"id": "academy", "level": "current", "kind": "Course", "title": "All Anthropic Academy courses",
+     "url": "https://anthropic.skilljar.com/", "blurb": "Every free course, including the API and MCP tracks."},
+]
+
+WINDOW_DAYS = 30
+MIN_SESSIONS = 5       # below this there isn't enough to judge habits
+LONG_PROMPTS = 40      # a session past this many prompts is "long"
+SHORT_WORDS = 4        # a first prompt this short rarely carries enough context
+BUSIEST = 8            # how many projects to check for CLAUDE.md
+
+
+def _has_memory(cwd):
+    p = Path(cwd)
+    return any((p / f).is_file() for f in ("CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md"))
+
+
+def _own_hooks(cfg):
+    """True/False if settings.json has hooks besides Session Pulse's; None if unreadable."""
+    try:
+        hooks = json.loads((cfg.claude / "settings.json").read_text()).get("hooks") or {}
+    except (OSError, ValueError, AttributeError):
+        return None
+    text = json.dumps(hooks)
+    return text.count('"command"') > text.count("-m sessionpulse hook")
+
+
+def suggest(cfg, sessions, now=None):
+    now = now or datetime.now().astimezone()
+    cutoff = (now - timedelta(days=WINDOW_DAYS)).isoformat()
+    recent = [s for s in sessions if (s.get("end") or "") >= cutoff and s.get("prompts")]
+    out = {"window_days": WINDOW_DAYS, "sessions": len(recent), "suggestions": [],
+           "strengths": [], "library": LIBRARY}
+    if len(recent) < MIN_SESSIONS:
+        return out
+
+    tools = {}
+    for s in sessions:  # feature use counts over all history: one use is enough to know it
+        for k, v in (s.get("tool_names") or {}).items():
+            tools[k] = tools.get(k, 0) + v
+    agents = sum(s.get("agents") or 0 for s in sessions)
+
+    def add(sid, title, why, links):
+        out["suggestions"].append({"id": sid, "title": title, "why": why, "links": links})
+
+    hours = {}
+    for s in recent:
+        if s.get("cwd"):
+            hours[s["cwd"]] = hours.get(s["cwd"], 0) + (s.get("hours") or 0)
+    busiest = sorted(hours, key=hours.get, reverse=True)[:BUSIEST]
+    missing = [s for s in busiest if Path(s) != Path.home() and Path(s).is_dir() and not _has_memory(s)]
+    if missing:
+        names = ", ".join(Path(m).name for m in missing[:4]) + (" …" if len(missing) > 4 else "")
+        add("memory", "Give your projects a CLAUDE.md",
+            f"{len(missing)} of your {len(busiest)} busiest projects have none ({names}). "
+            "Run /init in one to start it.", ["memory", "best-practices"])
+    else:
+        out["strengths"].append("Your busiest projects have a CLAUDE.md")
+
+    long_ = [s for s in recent if (s.get("prompts") or 0) >= LONG_PROMPTS]
+    if len(long_) >= 2:
+        add("context", "Keep sessions short and focused",
+            f"{len(long_)} sessions in the last {WINDOW_DAYS} days ran past {LONG_PROMPTS} prompts. "
+            "Long sessions fill the context, which costs tokens and makes earlier details easier to lose. "
+            "Use /clear between unrelated tasks.", ["context", "costs", "course-cc"])
+
+    short = [s for s in recent if 0 < len((s.get("first_prompt") or "").split()) <= SHORT_WORDS]
+    if len(short) >= 3 and len(short) / len(recent) >= 0.25:
+        add("prompting", "Open with more context",
+            f"{len(short)} of {len(recent)} recent sessions started with {SHORT_WORDS} words or fewer. "
+            "Say what you want, where it is and how you'll judge it done.",
+            ["prompting", "prompt-tutorial", "eng-blog"])
+
+    def feature(used, sid, title, why, links, strength):
+        if used:
+            out["strengths"].append(strength)
+        else:
+            add(sid, title, why, links)
+
+    feature(tools.get("ExitPlanMode") or tools.get("EnterPlanMode"), "plan-mode", "Try plan mode on bigger changes",
+            "None of your sessions used plan mode. Press Shift+Tab until it shows plan mode, and Claude "
+            "proposes a plan before it touches files.", ["plan-mode", "workflows"], "You use plan mode")
+    feature(agents or tools.get("Agent") or tools.get("Task"), "subagents", "Hand side-work to subagents",
+            "No session used a subagent yet. They do research or reviews in their own context, "
+            "so your main session stays clean.", ["subagents"], "You use subagents")
+    feature(tools.get("Skill"), "skills", "Turn repeated instructions into a skill",
+            "No session used a skill yet.", ["skills", "course-skills"], "You use skills")
+    feature(any(k.startswith("mcp__") for k in tools), "mcp", "Connect the tools you work in",
+            "No session used an MCP server yet.", ["mcp", "course-mcp"], "You connect tools through MCP")
+    own = _own_hooks(cfg)
+    if own is not None:
+        feature(own, "hooks", "Automate the routine with hooks",
+                "Your settings have no hooks of your own yet.", ["hooks"], "You automate with hooks")
+    return out

sessionpulse/reader.py

@@ -0,0 +1,333 @@
+"""Reads Claude Code's own files and turns them into one JSON-able snapshot.
+
+Sources (all read-only):
+  <claude_dir>/sessions/*.json        one file per running CLI process
+  <claude_dir>/projects/*/*.jsonl     session transcripts
+  <claude_dir>/projects/*/<id>/subagents/*.jsonl   subagent transcripts
+  <data_dir>/events.jsonl             start/exit events written by our hook
+
+None of these formats is documented by Anthropic, so every field is read
+defensively and anything surprising is counted in snapshot["health"] instead
+of raising. The dashboard shows those warnings so a Claude Code update that
+changes a format is visible rather than silently producing wrong numbers.
+"""
+import json
+import os
+import re
+import threading
+from collections import defaultdict
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from . import learn, todos
+from .config import Config
+
+TESTED_CLI = (2, 1)  # newest Claude Code minor version these parsers were checked against
+LIVE_KEYS = ("pid", "sessionId", "status")
+
+_cache = {}  # path -> (mtime_ns, size, summary)
+lock = threading.Lock()
+
+
+def local(s):
+    return datetime.fromisoformat(s.replace("Z", "+00:00")).astimezone()
+
+
+def text_of(content):
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "\n".join(c.get("text", "") for c in content
+                         if isinstance(c, dict) and c.get("type") == "text")
+    return ""
+
+
+def is_noise(t):
+    """Messages the CLI injects (command output, skill text, interrupts) rather than prompts."""
+    t = t.strip()
+    return (not t or t.startswith("<") or t.startswith("Caveat:")
+            or t.startswith("Base directory for this skill")
+            or "[Request interrupted" in t)
+
+
+def active_hours(stamps, gap=timedelta(minutes=30), min_block=timedelta(minutes=15)):
+    if not stamps:
+        return 0.0
+    stamps = sorted(stamps)
+    total, start, prev = timedelta(), stamps[0], stamps[0]
+    for t in stamps[1:]:
+        if t - prev > gap:
+            total += max(prev - start, min_block)
+            start = t
+        prev = t
+    total += max(prev - start, min_block)
+    return total.total_seconds() / 3600
+
+
+def project_name(cwd):
+    if not cwd:
+        return "?"
+    home = str(Path.home())
+    if cwd == home:
+        return "~"
+    if cwd.startswith(home + os.sep):
+        return os.path.relpath(cwd, home).replace(os.sep, "/")
+    return cwd
+
+
+def parse_transcript(path, main=True):
+    """Summarise one transcript file.
+
+    Token usage is de-duplicated by message id: the CLI writes one line per
+    content block, and each line repeats the same usage object."""
+    s = {"cwd": None, "first": None, "last": None, "prompts": 0, "first_prompt": "",
+         "last_prompt": "", "models": defaultdict(int), "version": None, "title": None,
+         "usage": defaultdict(int), "days": defaultdict(lambda: defaultdict(int)),
+         "stamps": [], "tools": 0, "tool_names": defaultdict(int), "bad_lines": 0, "lines": 0, "usage_msgs": 0}
+    seen = set()
+    with open(path, errors="replace") as f:
+        for line in f:
+            s["lines"] += 1
+            try:
+                e = json.loads(line)
+            except ValueError:
+                s["bad_lines"] += 1
+                continue
+            if not isinstance(e, dict):
+                s["bad_lines"] += 1
+                continue
+            typ = e.get("type")
+            if main and typ in ("custom-title", "summary"):
+                s["title"] = e.get("customTitle") or e.get("summary") or s["title"]
+            if s["cwd"] is None and isinstance(e.get("cwd"), str):
+                s["cwd"] = e["cwd"]
+            v = e.get("version")
+            if isinstance(v, str) and (_version_tuple(v) or ()) >= (_version_tuple(s["version"]) or ()):
+                s["version"] = v  # a resumed session can span CLI upgrades; keep the newest
+            try:
+                t = local(e["timestamp"])
+            except (KeyError, TypeError, ValueError, AttributeError):
+                continue
+            s["first"] = min(s["first"] or t, t)
+            s["last"] = max(s["last"] or t, t)
+            msg = e.get("message") if isinstance(e.get("message"), dict) else {}
+            if main and not e.get("isSidechain"):
+                s["stamps"].append(t)
+                if typ == "user" and msg.get("role") == "user":
+                    body = text_of(msg.get("content"))
+                    if not is_noise(body):
+                        body = re.sub(r"\s+", " ", body).strip()
+                        s["prompts"] += 1
+                        s["first_prompt"] = s["first_prompt"] or body[:300]
+                        s["last_prompt"] = body[:300]
+            if typ != "assistant":
+                continue
+            content = msg.get("content")
+            for c in content if isinstance(content, list) else []:
+                if isinstance(c, dict) and c.get("type") == "tool_use":
+                    s["tools"] += 1
+                    if isinstance(c.get("name"), str):
+                        s["tool_names"][c["name"]] += 1
+            u = msg.get("usage")
+            key = msg.get("id") or e.get("requestId") or e.get("uuid")
+            if not isinstance(u, dict) or key in seen:
+                continue
+            seen.add(key)
+            model = msg.get("model") or "unknown"
+            if model.startswith("<"):  # synthetic messages, e.g. "<synthetic>"
+                continue
+            s["usage_msgs"] += 1
+            vals = {"input": u.get("input_tokens") or 0,
+                    "output": u.get("output_tokens") or 0,
+                    "cache_write": u.get("cache_creation_input_tokens") or 0,
+                    "cache_read": u.get("cache_read_input_tokens") or 0}
+            s["models"][model] += vals["input"] + vals["output"]
+            day = t.date().isoformat()
+            for k, v in vals.items():
+                if isinstance(v, (int, float)):
+                    s["usage"][k] += v
+                    s["days"][day][f"{model}|{k}"] += v
+    return s
+
+
+def _cached(path, main=True):
+    try:
+        st = os.stat(path)
+    except OSError:
+        return None
+    hit = _cache.get(path)
+    if hit and hit[0] == st.st_mtime_ns and hit[1] == st.st_size:
+        return hit[2]
+    try:
+        summ = parse_transcript(path, main)
+    except OSError:
+        return None
+    _cache[path] = (st.st_mtime_ns, st.st_size, summ)
+    return summ
+
+
+def pid_alive(pid):
+    if not isinstance(pid, int) or pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+
+
+def read_live(claude: Path, health):
+    live = {}
+    d = claude / "sessions"
+    if not d.is_dir():
+        health["warnings"].append(f"{d} not found: live sessions can't be shown "
+                                  "(older Claude Code, or a changed layout).")
+        return live
+    for p in d.glob("*.json"):
+        try:
+            j = json.loads(p.read_text())
+        except (OSError, ValueError):
+            continue
+        if not isinstance(j, dict) or any(k not in j for k in LIVE_KEYS):
+            health["live_unrecognised"] += 1
+            continue
+        if not pid_alive(j.get("pid")):
+            continue
+        live[j["sessionId"]] = {
+            "pid": j.get("pid"), "status": j.get("status"), "name": j.get("name"),
+            "kind": j.get("kind"), "entrypoint": j.get("entrypoint"),
+            "startedAt": j.get("startedAt"),
+            "updatedAt": j.get("statusUpdatedAt") or j.get("updatedAt"),
+        }
+    return live
+
+
+def read_events(path: Path):
+    out = []
+    if path.exists():
+        with open(path, errors="replace") as f:
+            for line in f:
+                try:
+                    e = json.loads(line)
+                except ValueError:
+                    continue
+                if isinstance(e, dict) and e.get("ts"):
+                    out.append(e)
+    return out
+
+
+def _version_tuple(v):
+    try:
+        return tuple(int(x) for x in v.split("."))
+    except (AttributeError, ValueError):
+        return None
+
+
+def snapshot(cfg: Config):
+    claude = cfg.claude
+    gap = timedelta(minutes=cfg.gap_minutes)
+    min_block = timedelta(minutes=cfg.min_block_minutes)
+    health = {"warnings": [], "files": 0, "bad_lines": 0, "lines": 0,
+              "live_unrecognised": 0, "newest_cli": None}
+    sessions = {}
+    proj_dir = claude / "projects"
+    if not proj_dir.is_dir():
+        health["warnings"].append(f"No transcripts at {proj_dir}. Is claude_dir right?")
+    newest = None
+    usage_msgs = 0
+    for pdir in proj_dir.iterdir() if proj_dir.is_dir() else []:
+        if not pdir.is_dir():
+            continue
+        for tf in pdir.glob("*.jsonl"):
+            sid = tf.stem
+            s = _cached(str(tf))
+            if not s:
+                continue
+            health["files"] += 1
+            health["bad_lines"] += s["bad_lines"]
+            health["lines"] += s["lines"]
+            usage_msgs += s["usage_msgs"]
+            if not s["first"]:
+                continue
+            if s["version"] and (newest is None or
+                                 (_version_tuple(s["version"]) or ()) > (_version_tuple(newest) or ())):
+                newest = s["version"]
+            usage = dict(s["usage"])
+            days = {d: dict(v) for d, v in s["days"].items()}
+            models = dict(s["models"])
+            tool_names = dict(s["tool_names"])
+            agents = 0
+            for af in (pdir / sid / "subagents").glob("*.jsonl"):
+                a = _cached(str(af), main=False)
+                if not a:
+                    continue
+                agents += 1
+                for k, v in a["usage"].items():
+                    usage[k] = usage.get(k, 0) + v
+                for m, v in a["models"].items():
+                    models[m] = models.get(m, 0) + v
+                for d, kv in a["days"].items():
+                    dd = days.setdefault(d, {})
+                    for k, v in kv.items():
+                        dd[k] = dd.get(k, 0) + v
+            if not s["prompts"] and not usage.get("output"):
+                continue
+            by_day = defaultdict(list)
+            for t in s["stamps"]:
+                by_day[t.date().isoformat()].append(t)
+            sessions[sid] = {
+                "id": sid, "cwd": s["cwd"], "project": project_name(s["cwd"]), "transcript": str(tf),
+                "title": s["title"], "start": s["first"].isoformat(), "end": s["last"].isoformat(),
+                "prompts": s["prompts"], "first_prompt": s["first_prompt"],
+                "last_prompt": s["last_prompt"], "tools": s["tools"], "tool_names": tool_names,
+                "agents": agents,
+                "version": s["version"], "usage": usage, "days": days,
+                "model": max(models, key=models.get) if models else None,
+                "hours": round(active_hours(s["stamps"], gap, min_block), 2),
+                "hours_by_day": {d: round(active_hours(v, gap, min_block), 2)
+                                 for d, v in by_day.items()},
+            }
+
+    health["newest_cli"] = newest
+    if health["lines"] and health["bad_lines"] / health["lines"] > 0.05:
+        health["warnings"].append(f"{health['bad_lines']} of {health['lines']} transcript lines "
+                                  "could not be read; the transcript format may have changed.")
+    if health["files"] and sessions and not usage_msgs:
+        health["warnings"].append("No token usage found in any transcript; "
+                                  "the usage format may have changed.")
+    if health["live_unrecognised"]:
+        health["warnings"].append(f"{health['live_unrecognised']} live-session files had an "
+                                  "unexpected shape and were skipped.")
+    vt = _version_tuple(newest)
+    if vt and vt[:2] > TESTED_CLI:
+        health["warnings"].append(f"Claude Code {newest} is newer than the version Session Pulse "
+                                  f"was tested with ({'.'.join(map(str, TESTED_CLI))}). "
+                                  "Check the numbers look right.")
+
+    live = read_live(claude, health)
+    events = read_events(cfg.events_file)
+    exits = {e.get("session"): e for e in events if e.get("event") == "SessionEnd"}
+    for sid, s in sessions.items():
+        if sid in live:
+            s["state"] = live[sid]["status"] or "running"
+            s["live"] = live[sid]
+        elif sid in exits:
+            s["state"] = "exited"
+            s["exit_reason"] = exits[sid].get("reason")
+            s["exit_at"] = exits[sid].get("ts")
+        else:
+            s["state"] = "closed"
+    for sid, l in live.items():  # just started; no transcript written yet
+        if sid not in sessions:
+            sessions[sid] = {"id": sid, "project": "?", "state": l["status"] or "running",
+                             "live": l, "start": None, "end": None, "prompts": 0,
+                             "usage": {}, "days": {}, "hours": 0, "hours_by_day": {}}
+    for e in events:
+        s = sessions.get(e.get("session"))
+        e["project"] = s["project"] if s else project_name(e.get("cwd"))
+    sessions = list(sessions.values())
+    return {"now": datetime.now().astimezone().isoformat(), "refresh": cfg.refresh_seconds,
+            "sessions": sessions, "events": events[-300:], "health": health,
+            "todos": todos.load(cfg), "learn": learn.suggest(cfg, sessions)}