claude-session-logger 0.1.0__py3-none-any.whl

claude_session_logger/__init__.py

@@ -0,0 +1,3 @@
+"""Claude Code session logging + shared issue tracking via DuckDB + MotherDuck."""
+
+__version__ = "0.1.0"

claude_session_logger/_setup.py

@@ -0,0 +1,176 @@
+"""Post-install setup: LaunchAgent + Claude Code hooks + token check.
+
+Installed as the `claude-session-logger-setup` command. Idempotent: re-running
+migrates old script-path hooks to the installed commands and never duplicates.
+
+The flush LaunchAgent invokes `<python> -m claude_session_logger.cli flush`; it
+does NOT embed the token — the code resolves it from ~/.config/motherduck/token
+in-process, so no secret lands in the plist.
+"""
+import argparse
+import json
+import os
+import plistlib
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+LABEL = "com.keithfajardo.claude-session-logger.flush"
+DEFAULT_SETTINGS = Path.home() / ".claude" / "settings.json"
+DEFAULT_PLIST = Path.home() / "Library" / "LaunchAgents" / f"{LABEL}.plist"
+TOKEN_FILE = Path.home() / ".config" / "motherduck" / "token"
+
+# Substrings marking a hook command as managed by THIS tool. Used to strip stale
+# entries (old absolute script paths included) before re-adding, so a re-run or a
+# migration from the pre-package layout is idempotent.
+MANAGED_MARKERS = ("claude_session_logger", "claude-session-logger",
+                   "log_session.py", "memory_sync.py", LABEL)
+
+
+def _cli(*a):
+    return " ".join([sys.executable, "-m", "claude_session_logger.cli", *a])
+
+
+def _mem(*a):
+    return " ".join([sys.executable, "-m", "claude_session_logger.memory", *a])
+
+
+def _kick():
+    return f"launchctl kickstart gui/$(id -u)/{LABEL}"
+
+
+def desired_hooks():
+    """The hook blocks this tool owns, keyed by Claude Code event."""
+    return {
+        "SessionStart": [{
+            "hooks": [
+                {"type": "command", "command": _cli("recent")},
+                {"type": "command", "command": _cli("inbox", "--count")},
+                {"type": "command", "command": _kick()},
+                {"type": "command",
+                 "command": _mem("pull", "2>&1", "||", "true"),
+                 "timeout": 30,
+                 "statusMessage": "Pulling memory from MotherDuck"},
+            ]
+        }],
+        "PostToolUse": [{
+            "matcher": "Write|Edit",
+            "hooks": [{"type": "command",
+                       "command": _mem("hook", "2>/dev/null", "||", "true"),
+                       "async": True}],
+        }],
+        "SessionEnd": [{
+            "hooks": [{"type": "command",
+                       "command": _cli("record", "--no-sync") + "; " + _kick()}],
+        }],
+    }
+
+
+def _is_managed(cmd):
+    return any(m in cmd for m in MANAGED_MARKERS)
+
+
+def _strip_managed(blocks):
+    """Drop our hook entries (and blocks left empty) from one event's block list.
+
+    Blocks without a "hooks" key are left untouched (not ours). A block whose
+    every command is managed disappears entirely, so re-running can't duplicate.
+    """
+    out = []
+    for blk in blocks:
+        if "hooks" not in blk:
+            out.append(blk)
+            continue
+        kept = [h for h in blk["hooks"] if not _is_managed(h.get("command", ""))]
+        if kept:
+            nb = dict(blk)
+            nb["hooks"] = kept
+            out.append(nb)
+    return out
+
+
+def merge_hooks(settings, desired):
+    hooks = settings.setdefault("hooks", {})
+    for event, blocks in desired.items():
+        hooks[event] = _strip_managed(hooks.get(event, [])) + blocks
+    return settings
+
+
+def setup_hooks(settings_path=DEFAULT_SETTINGS):
+    if settings_path.exists():
+        settings = json.loads(settings_path.read_text())
+        shutil.copy(settings_path, settings_path.with_suffix(".json.bak"))
+        backup = " (backup: settings.json.bak)"
+    else:
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+        settings, backup = {}, ""
+    merge_hooks(settings, desired_hooks())
+    settings_path.write_text(json.dumps(settings, indent=2) + "\n")
+    print(f"✓ hooks merged into {settings_path}{backup}")
+    return True
+
+
+def setup_launchd(plist_path=DEFAULT_PLIST, load=True):
+    plist_path.parent.mkdir(parents=True, exist_ok=True)
+    plist = {
+        "Label": LABEL,
+        "ProgramArguments": ["/bin/sh", "-c", f"sleep 5; {_cli('flush')}"],
+        "RunAtLoad": False,
+    }
+    with open(plist_path, "wb") as f:
+        plistlib.dump(plist, f)
+    print(f"✓ LaunchAgent written to {plist_path}")
+    if not load:
+        return True
+    uid = os.getuid()
+    # bootout first (ignore "not loaded"), then bootstrap the fresh definition.
+    subprocess.run(["launchctl", "bootout", f"gui/{uid}/{LABEL}"],
+                   capture_output=True)
+    r = subprocess.run(["launchctl", "bootstrap", f"gui/{uid}", str(plist_path)],
+                       capture_output=True, text=True)
+    if r.returncode == 0:
+        print("✓ LaunchAgent loaded")
+    else:
+        print(f"⚠ load it manually: launchctl bootstrap gui/{uid} {plist_path}")
+    return True
+
+
+def check_token(token_file=TOKEN_FILE):
+    if token_file.exists():
+        print(f"✓ MotherDuck token present at {token_file}")
+        return True
+    print(f"⚠ no MotherDuck token at {token_file}\n"
+          "  Authenticate:  pip install motherduck && motherduck auth\n"
+          "  (or write the token file yourself, chmod 600). Local logging works "
+          "without it; cloud sync stays off until the token exists.")
+    return False
+
+
+def run_init():
+    subprocess.run([sys.executable, "-m", "claude_session_logger.cli", "init"],
+                   check=False)
+    print("✓ local schema initialized")
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="claude-session-logger-setup")
+    ap.add_argument("--settings", type=Path, default=DEFAULT_SETTINGS,
+                    help="path to Claude Code settings.json")
+    ap.add_argument("--no-launchd", action="store_true",
+                    help="skip the flush LaunchAgent (e.g. non-macOS)")
+    ap.add_argument("--no-load", action="store_true",
+                    help="write the plist but don't launchctl-load it")
+    a = ap.parse_args(argv)
+    print("Setting up claude-session-logger…\n")
+    run_init()
+    setup_hooks(a.settings)
+    if not a.no_launchd:
+        setup_launchd(load=not a.no_load)
+    ok = check_token()
+    print("\nDone." if ok else "\nDone (cloud sync pending token).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

claude_session_logger/classify.py

@@ -0,0 +1,73 @@
+"""Infer a session's `session_type`.
+
+Built-in DEFAULT_RULES are the template. Users extend/override them with an optional
+YAML file at ~/.claude/claude-session-logger/session_types.yaml — user rules are
+checked FIRST (so they can override a template type or add new ones), then defaults,
+then the `general` fallback. First match wins.
+
+This runs inside the SessionEnd hook (no TTY), so loading must never raise: a missing
+file, missing PyYAML, or malformed YAML all degrade silently to the defaults.
+"""
+from pathlib import Path
+
+CONFIG_PATH = (Path.home() / ".claude" / "claude-session-logger"
+               / "session_types.yaml")
+
+# The template. Each rule: a `type` plus case-insensitive substrings to match against
+# the session's skills and/or its "project cwd" text. Same shape the YAML file uses.
+DEFAULT_RULES = [
+    {"type": "dbt", "skills": ["dbt", "kimball"], "path": ["dbt"]},
+    {"type": "debugging", "skills": ["systematic-debugging"]},
+    {"type": "research", "skills": ["deep-research", "brainstorming", "research"]},
+    {"type": "planning", "skills": ["writing-plans", "executing-plans"]},
+]
+
+
+def _normalize_rules(data):
+    """Coerce parsed YAML into clean rule dicts; drop anything malformed."""
+    out = []
+    for r in data if isinstance(data, list) else []:
+        if isinstance(r, dict) and r.get("type"):
+            out.append({
+                "type": str(r["type"]),
+                "skills": [str(s).lower() for s in (r.get("skills") or [])],
+                "path": [str(p).lower() for p in (r.get("path") or [])],
+            })
+    return out
+
+
+def load_user_rules(path=CONFIG_PATH):
+    """User rules from the YAML file, or [] — never raises (hook-safe)."""
+    if not path.exists():
+        return []
+    try:
+        import yaml  # lazy: package imports fine even without PyYAML installed
+    except ImportError:
+        return []
+    try:
+        data = yaml.safe_load(path.read_text()) or []
+    except Exception:
+        return []  # malformed YAML → ignore, fall back to defaults
+    return _normalize_rules(data)
+
+
+def effective_rules():
+    """User rules first (override/extend), then the built-in template."""
+    return load_user_rules() + DEFAULT_RULES
+
+
+def _matches(rule, skills_lc, path_text):
+    # .get/.lower so hand-written DEFAULT_RULES (may omit a key) and normalized user
+    # rules both work.
+    if any(kw.lower() in sk for kw in rule.get("skills", []) for sk in skills_lc):
+        return True
+    return any(kw.lower() in path_text for kw in rule.get("path", []))
+
+
+def infer_session_type(skills_used, project, cwd, rules=None):
+    skills_lc = [str(x).lower() for x in (skills_used or [])]
+    path_text = f"{project or ''} {cwd or ''}".lower()
+    for rule in (effective_rules() if rules is None else rules):
+        if _matches(rule, skills_lc, path_text):
+            return rule["type"]
+    return "general"

claude_session_logger/cli.py

@@ -0,0 +1,336 @@
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from . import classify
+from . import cost as cost_mod
+from . import db
+from . import identity
+from . import resolve
+from . import transcript
+
+SYNC_LOG = Path.home() / ".claude" / "claude-session-logger" / "sync.log"
+
+
+def _log_error(msg):
+    SYNC_LOG.parent.mkdir(parents=True, exist_ok=True)
+    with open(SYNC_LOG, "a") as f:
+        f.write(msg + "\n")
+
+
+def _minutes(start, end):
+    if not start or not end:
+        return None
+    parse = lambda s: datetime.fromisoformat(s.replace("Z", "+00:00"))
+    return round((parse(end) - parse(start)).total_seconds() / 60, 2)
+
+
+def _norm_ts(s):
+    # DuckDB TIMESTAMP cast rejects the trailing 'Z' — strip it for storage.
+    return s.replace("Z", "") if s else None
+
+
+def build_row(data, payload, cost_usd, session_type):
+    cwd = data["cwd"] or payload.get("cwd")
+    ts = data["timestamps"]
+    started = ts[0] if ts else None
+    ended = ts[-1] if ts else None
+    return {
+        "session_id": data["session_id"] or payload.get("session_id"),
+        "project": Path(cwd).name if cwd else None,
+        "cwd": cwd,
+        "session_date": started[:10] if started else None,
+        "started_at": _norm_ts(started),
+        "ended_at": _norm_ts(ended),
+        "duration_min": _minutes(started, ended),
+        "models": ",".join(data["models"]),
+        "input_tokens": data["input_tokens"],
+        "output_tokens": data["output_tokens"],
+        "cache_write_tokens": data["cache_write_tokens"],
+        "cache_read_tokens": data["cache_read_tokens"],
+        "total_tokens": data["total_tokens"],
+        "cost_usd": cost_usd,
+        "message_count": data["message_count"],
+        "tool_call_count": data["tool_call_count"],
+        "skills_used": ",".join(data["skills_used"]),
+        "git_branch": data["git_branch"],
+        "cc_version": data["cc_version"],
+        "title": data["title"],
+        "session_type": session_type,
+        "created_by": identity.current_user(),
+    }
+
+
+def _try_sync(con):
+    try:
+        db.sync(con, cloud_dsn=db.CLOUD_DSN)
+    except Exception as e:  # cloud unreachable / token missing — never fatal
+        _log_error(f"sync failed: {e}")
+
+
+def cmd_init(args, stdin):
+    con = db.connect(db.LOCAL_DB)
+    db.create_tables(con)
+    con.close()
+
+
+def cmd_record(args, stdin):
+    payload = json.load(stdin)
+    records = transcript.read_transcript(payload["transcript_path"])
+    data = transcript.parse_lines(records)
+    prices = cost_mod.load_prices()
+    cost_usd, unknown = cost_mod.compute_cost(data["usage_by_model"], prices)
+    if unknown:
+        _log_error(f"unknown models (cost=0 for these): {unknown}")
+    cwd = data["cwd"] or payload.get("cwd")
+    project = Path(cwd).name if cwd else None
+    session_type = classify.infer_session_type(data["skills_used"], project, cwd)
+    row = build_row(data, payload, cost_usd, session_type)
+    con = db.connect(db.LOCAL_DB)
+    db.create_tables(con)
+    db.upsert_session(con, row)
+    if not getattr(args, "no_sync", False):
+        _try_sync(con)
+    con.close()
+
+
+def cmd_log(args, stdin):
+    session_id = args.session_id or resolve.resolve_session_id()
+    con = db.connect(db.LOCAL_DB)
+    db.create_tables(con)
+    entry_id = db.insert_log_entry(con, session_id, args.category, args.status,
+                                   args.title, args.body,
+                                   created_by=identity.current_user())
+    _try_sync(con)
+    con.close()
+    # Surface the id so it can be resolved/updated later without a separate list.
+    print(f"logged {args.category} ({args.status}) id={entry_id}")
+
+
+def _resolve_entry_id(con, args):
+    """Return the entry id to act on, from --id or a --title-match lookup.
+
+    On an unusable title match (no hit / multiple hits), writes a message to
+    stderr and returns None so the caller can exit non-zero.
+    """
+    if args.id:
+        return args.id
+    matches = db.find_log_entries_by_title(con, args.title_match)
+    if not matches:
+        sys.stderr.write(f"no log entry with title matching {args.title_match!r}\n")
+        return None
+    if len(matches) > 1:
+        sys.stderr.write(
+            f"{len(matches)} entries match {args.title_match!r} — disambiguate by --id:\n")
+        for eid, cat, status, title in matches:
+            sys.stderr.write(f"  {eid}  [{cat}/{status}] {title}\n")
+        return None
+    return matches[0][0]
+
+
+def cmd_resolve(args, stdin):
+    if not args.id and not args.title_match:
+        sys.stderr.write("resolve needs --id or --title-match\n")
+        raise SystemExit(2)
+    con = db.connect(db.LOCAL_DB)
+    db.create_tables(con)
+    entry_id = _resolve_entry_id(con, args)
+    if entry_id is None:
+        con.close()
+        raise SystemExit(1)
+    ok = db.update_log_status(con, entry_id, args.status, args.note,
+                              updated_by=identity.current_user())
+    if not ok:
+        sys.stderr.write(f"no log entry with id {entry_id}\n")
+        con.close()
+        raise SystemExit(1)
+    _try_sync(con)
+    con.close()
+    print(f"{entry_id} -> {args.status}")
+
+
+def cmd_list(args, stdin):
+    con = db.connect(db.LOCAL_DB)
+    db.create_tables(con)
+    rows = db.list_log_entries(con, category=args.category, status=args.status,
+                               open_only=args.open_only, limit=args.limit)
+    for r in rows:
+        print("\t".join("" if v is None else str(v) for v in r))
+    con.close()
+
+
+def cmd_show(args, stdin):
+    # Read-only: prints ONE entry's full body. Replaces hand-written duckdb
+    # one-liners (token-heavy, fragile). Address by id prefix or title words.
+    if not args.id and not args.title_match:
+        sys.stderr.write("show needs an id prefix or --title-match\n")
+        raise SystemExit(2)
+    con = db.connect(db.LOCAL_DB, read_only=True)
+    try:
+        rows = db.get_log_entries(con, id_prefix=args.id,
+                                  title_substr=args.title_match)
+    finally:
+        con.close()
+    if not rows:
+        target = args.id or args.title_match
+        sys.stderr.write(f"no log entry matching {target!r}\n")
+        raise SystemExit(1)
+    if len(rows) > 1:
+        sys.stderr.write(f"{len(rows)} entries match — narrow it down:\n")
+        for _id, cat, status, title, *_ in rows:
+            sys.stderr.write(f"  {_id}  [{cat}/{status}] {title}\n")
+        raise SystemExit(1)
+    _id, cat, status, title, body, logged, updated, cby, uby = rows[0]
+    print(f"id:      {_id}")
+    print(f"type:    {cat} / {status}")
+    print(f"title:   {title}")
+    print(f"created: {logged}  by {cby or '?'}")
+    if updated:
+        print(f"updated: {updated}  by {uby or '?'}")
+    print("body:")
+    print(body or "(empty)")
+
+
+def cmd_recent(args, stdin):
+    # Read-only path: no write lock needed, so readers coexist when no writer
+    # holds the file. Startup banner is non-essential — if the db is missing,
+    # locked past retries, or has no tables yet, skip silently (no traceback).
+    try:
+        con = db.connect(db.LOCAL_DB, read_only=True)
+    except Exception as e:
+        _log_error(f"recent skipped (connect): {e}")
+        return
+    try:
+        rows = db.recent_sessions(con, limit=args.limit)
+    except Exception as e:
+        _log_error(f"recent skipped (query): {e}")
+        return
+    finally:
+        con.close()
+    if not rows:
+        return
+    print(f"Recent sessions (last {len(rows)}):")
+    for session_id, session_date, project, title, _ended in rows:
+        print(f"  • {session_date}  [{project or '?'}]  {title or '(untitled)'}")
+        print(f"      resume: claude --resume {session_id}")
+    print("Continue most recent in this dir: claude --continue")
+
+
+INBOX_CMD = "claude-session-logger inbox"
+
+
+def cmd_inbox(args, stdin):
+    me = identity.current_user()
+    if getattr(args, "count", False):
+        # Badge path: read-only so it coexists with the flush writer and never
+        # advances the watermark (only the full view marks changes as seen).
+        try:
+            con = db.connect(db.LOCAL_DB, read_only=True)
+        except Exception as e:
+            _log_error(f"inbox --count skipped (connect): {e}")
+            return
+        try:
+            rows = db.inbox_changes(con, me, db.get_meta(con, "inbox_watermark"))
+        except Exception as e:
+            _log_error(f"inbox --count skipped (query): {e}")
+            return
+        finally:
+            con.close()
+        if rows:
+            print(f"📬 {len(rows)} shared issue update(s) — run: {INBOX_CMD}")
+        return
+    # Full view: list changes by others, then advance the watermark to now.
+    con = db.connect(db.LOCAL_DB)
+    db.create_tables(con)
+    rows = db.inbox_changes(con, me, db.get_meta(con, "inbox_watermark"))
+    if not rows:
+        print("Inbox empty — no shared issue changes by others.")
+    else:
+        print(f"Inbox — {len(rows)} change(s) by others since last check:")
+        for _id, category, status, title, actor, ts in rows:
+            print(f"  • [{category}/{status}] {title}")
+            print(f"      by {actor} at {ts}   id={_id}")
+    now = con.execute("SELECT timezone('UTC', now())").fetchone()[0]
+    db.set_meta(con, "inbox_watermark", now)
+    con.close()
+
+
+def cmd_flush(args, stdin):
+    # User-initiated (e.g. /sync-issue) and may race the SessionStart LaunchAgent
+    # flush, which holds the write lock for a whole cloud round-trip. Wait it out
+    # (~36s) instead of failing fast like the hook paths.
+    try:
+        con = db.connect(db.LOCAL_DB, retries=20, base_delay=0.3)
+    except Exception as e:
+        # Clean message instead of a traceback if the lock never frees.
+        print(f"sync skipped — db busy, another sync still running ({e})")
+        return
+    db.create_tables(con)
+    pending = con.execute(
+        "SELECT count(*) FROM log_entries WHERE synced = FALSE").fetchone()[0]
+    _try_sync(con)
+    remaining = con.execute(
+        "SELECT count(*) FROM log_entries WHERE synced = FALSE").fetchone()[0]
+    total, open_ct = con.execute(
+        "SELECT count(*), count(*) FILTER (WHERE status <> 'resolved') "
+        "FROM log_entries WHERE category = 'issue'").fetchone()
+    unseen = len(db.inbox_changes(con, identity.current_user(),
+                                  db.get_meta(con, "inbox_watermark")))
+    con.close()
+    if remaining:
+        # _try_sync swallows cloud errors; unsynced rows still queued means it failed.
+        print(f"sync incomplete — {remaining} change(s) still queued "
+              f"(cloud unreachable? see sync.log)")
+    else:
+        print(f"synced {pending} change(s) · {total} issue(s) "
+              f"({open_ct} open) · inbox {unseen} unseen")
+
+
+def main(argv=None, stdin=None):
+    argv = sys.argv[1:] if argv is None else argv
+    stdin = stdin if stdin is not None else sys.stdin
+    p = argparse.ArgumentParser()
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("init")
+    rp_rec = sub.add_parser("record")
+    rp_rec.add_argument("--no-sync", dest="no_sync", action="store_true")
+    sub.add_parser("flush")
+    lp = sub.add_parser("log")
+    lp.add_argument("--category", required=True)
+    lp.add_argument("--status", required=True)
+    lp.add_argument("--title", required=True)
+    lp.add_argument("--body", default="")
+    lp.add_argument("--session-id", dest="session_id", default=None)
+    rp = sub.add_parser("resolve")
+    rp.add_argument("--id", default=None)
+    rp.add_argument("--title-match", dest="title_match", default=None,
+                    help="resolve by case-insensitive title substring (must match exactly one)")
+    rp.add_argument("--status", required=True)
+    rp.add_argument("--note", default=None)
+    lp2 = sub.add_parser("list")
+    lp2.add_argument("--category", default=None)
+    lp2.add_argument("--status", default=None)
+    lp2.add_argument("--open", dest="open_only", action="store_true")
+    lp2.add_argument("--limit", type=int, default=None)
+    sp = sub.add_parser("show")
+    sp.add_argument("id", nargs="?", default=None,
+                    help="entry id or id prefix (e.g. b045dd70)")
+    sp.add_argument("--title-match", dest="title_match", default=None,
+                    help="show by case-insensitive title substring (must match one)")
+    rp_recent = sub.add_parser("recent")
+    rp_recent.add_argument("--limit", type=int, default=3)
+    rp_inbox = sub.add_parser("inbox")
+    rp_inbox.add_argument("--count", action="store_true",
+                          help="print only the unseen-count badge (read-only); "
+                               "without it, show the inbox and mark changes seen")
+    args = p.parse_args(argv)
+    {"init": cmd_init, "record": cmd_record,
+     "log": cmd_log, "flush": cmd_flush,
+     "resolve": cmd_resolve, "list": cmd_list, "show": cmd_show,
+     "recent": cmd_recent, "inbox": cmd_inbox}[args.cmd](args, stdin)
+
+
+if __name__ == "__main__":
+    main()

claude_session_logger/cost.py

@@ -0,0 +1,28 @@
+import json
+from pathlib import Path
+
+PRICES_PATH = Path(__file__).with_name("prices.json")
+
+
+def load_prices(path=PRICES_PATH):
+    with open(path) as f:
+        return json.load(f)
+
+
+def compute_cost(usage_by_model, prices):
+    """usage_by_model: {model: {"input","output","cache_write","cache_read": int}}.
+    prices: same shape, per 1M tokens. Returns (cost_usd, unknown_models)."""
+    total = 0.0
+    unknown = []
+    for model, u in usage_by_model.items():
+        p = prices.get(model)
+        if p is None:
+            unknown.append(model)
+            continue
+        total += (
+            u.get("input", 0) * p["input"]
+            + u.get("output", 0) * p["output"]
+            + u.get("cache_write", 0) * p["cache_write"]
+            + u.get("cache_read", 0) * p["cache_read"]
+        )
+    return total / 1_000_000, unknown