worklog-for-claude-code 0.1.0__py3-none-any.whl

worklog/config.py

@@ -0,0 +1,294 @@
+"""Configuration loading and validation.
+
+Config lives at ~/.config/claude-worklog/config.toml (XDG_CONFIG_HOME respected).
+"""
+from __future__ import annotations
+
+import os
+import re
+import socket
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # Ubuntu 22.04 ships Python 3.10
+    import tomli as tomllib
+
+
+def _xdg(var: str, default: str) -> Path:
+    return Path(os.environ.get(var) or Path.home() / default)
+
+
+CONFIG_PATH = _xdg("XDG_CONFIG_HOME", ".config") / "claude-worklog" / "config.toml"
+STATE_DIR = _xdg("XDG_STATE_HOME", ".local/state") / "claude-worklog"  # logs, lock
+DATA_DIR = _xdg("XDG_DATA_HOME", ".local/share") / "claude-worklog"  # summarizer cwd
+SUMMARIZER_CWD = DATA_DIR / "summarizer"
+
+# Claude Code's default config dir. For this one we must NOT set CLAUDE_CONFIG_DIR,
+# because the default install keeps some state outside it (e.g. ~/.claude.json).
+DEFAULT_CLAUDE_DIR = Path.home() / ".claude"
+
+_NAME_RE = re.compile(r"^[A-Za-z0-9_-]{1,40}$")
+_ACCOUNT_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,100}$")
+
+EXAMPLE_CONFIG = """\
+# claude-worklog configuration
+# Name this device. Must be unique across your machines (letters, digits, _ -).
+device_name = "{device}"
+
+# Local clone of your PRIVATE data repo (GitHub, GitLab or Bitbucket all work).
+store_repo = "~/claude-worklog-data"
+
+# One [[accounts]] block per Claude account used on THIS device.
+# config_dir is where that account's Claude Code data lives.
+[[accounts]]
+name = "personal"
+config_dir = "~/.claude"
+
+# [[accounts]]
+# name = "work"
+# config_dir = "~/.claude-work"   # used via: CLAUDE_CONFIG_DIR=~/.claude-work claude
+
+# Several accounts can share ONE folder (switching with /logout and /login).
+# Each extra account is matched by the login recorded at session start; name them in
+# the web UI (Settings > Detected accounts). The account without match_* is the
+# folder's default and gets every session that matches no other account.
+# [[accounts]]
+# name = "client"
+# config_dir = "~/.claude"
+# match_account_id = "..."        # or: match_email = "you@example.com"
+
+[collect]
+misc_label = "R&D / misc"   # sessions run outside any git repo
+include_commits = true      # read your own commits (git log --author=<your git email>)
+max_prompts_per_session = 30
+max_prompt_chars = 300
+
+[report]
+use_ai = true                 # summarize with `claude -p`; false = plain listing
+summarizer_account = "personal"
+claude_bin = "claude"         # use an absolute path if running from cron
+ai_timeout_seconds = 180
+"""
+
+
+class ConfigError(Exception):
+    """Raised for missing or invalid configuration."""
+
+
+@dataclass(frozen=True)
+class Account:
+    name: str
+    config_dir: Path
+    # Optional: which login this account is when several accounts share config_dir.
+    # Kept in the local config only; never written to records.
+    match_account_id: str | None = None
+    match_email: str | None = None
+
+    @property
+    def matched(self) -> bool:
+        return bool(self.match_account_id or self.match_email)
+
+
+@dataclass
+class Config:
+    device: str
+    store_repo: Path
+    accounts: list[Account]
+    misc_label: str = "R&D / misc"
+    include_commits: bool = True
+    max_prompts: int = 30
+    max_prompt_chars: int = 300
+    use_ai: bool = True
+    summarizer_account: str | None = None
+    claude_bin: str = "claude"
+    ai_timeout: int = 180
+    path: Path = field(default=CONFIG_PATH)
+
+    def account(self, name: str) -> Account | None:
+        return next((a for a in self.accounts if a.name == name), None)
+
+    def accounts_by_dir(self) -> dict[Path, list[Account]]:
+        """Accounts grouped by config folder, in config file order."""
+        out: dict[Path, list[Account]] = {}
+        for a in self.accounts:
+            out.setdefault(a.config_dir, []).append(a)
+        return out
+
+    def default_account(self, config_dir: Path) -> Account:
+        """The folder's fallback: its first account without match_*, else its first account."""
+        group = self.accounts_by_dir()[config_dir]
+        return next((a for a in group if not a.matched), group[0])
+
+    def resolve_account(self, config_dir: Path, account_id: str | None = None,
+                        email: str | None = None) -> Account:
+        """Configured account for a session in `config_dir` run by the given login."""
+        group = self.accounts_by_dir()[config_dir]
+        if account_id:
+            hit = next((a for a in group if a.match_account_id == account_id), None)
+            if hit:
+                return hit
+        if email:
+            hit = next((a for a in group if a.match_email and a.match_email.casefold() == email.casefold()), None)
+            if hit:
+                return hit
+        return self.default_account(config_dir)
+
+
+def _expand(p: str) -> Path:
+    return Path(os.path.expandvars(p)).expanduser().resolve()
+
+
+def _check_name(kind: str, value: object) -> str:
+    if not isinstance(value, str) or not _NAME_RE.match(value):
+        raise ConfigError(f"{kind} {value!r} must be 1-40 chars of letters, digits, '_' or '-'")
+    return value
+
+
+def _int(section: dict, key: str, default: int, lo: int, hi: int) -> int:
+    v = section.get(key, default)
+    if not isinstance(v, int) or isinstance(v, bool) or not lo <= v <= hi:
+        raise ConfigError(f"{key} must be an integer between {lo} and {hi}")
+    return v
+
+
+def _match_id(name: str, v: object) -> str | None:
+    if v is None or v == "":
+        return None
+    if not isinstance(v, str) or not _ACCOUNT_ID_RE.match(v):
+        raise ConfigError(f"account {name}: match_account_id must be the account id from Claude Code")
+    return v
+
+
+def _match_email(name: str, v: object) -> str | None:
+    if v is None or v == "":
+        return None
+    if not isinstance(v, str) or len(v) > 254 or not re.match(r"^[^@\s]+@[^@\s]+$", v):
+        raise ConfigError(f"account {name}: match_email must be an e-mail address")
+    return v
+
+
+def _check_shared_dirs(accounts: list[Account]) -> None:
+    """Accounts sharing a folder must be distinguishable, or sessions would be counted twice."""
+    by_dir: dict[Path, list[Account]] = {}
+    for a in accounts:
+        by_dir.setdefault(a.config_dir, []).append(a)
+    for d, group in by_dir.items():
+        if len(group) < 2:
+            continue
+        defaults = [a.name for a in group if not a.matched]
+        if len(defaults) > 1:
+            raise ConfigError(f"accounts {', '.join(defaults)} share {d}: all but one need match_account_id "
+                              "or match_email (the one without is that folder's default)")
+        ids = [a.match_account_id for a in group if a.match_account_id]
+        emails = [a.match_email.casefold() for a in group if a.match_email]
+        if len(set(ids)) != len(ids) or len(set(emails)) != len(emails):
+            raise ConfigError(f"two accounts in {d} match the same login")
+
+
+def load_config(path: Path = CONFIG_PATH) -> Config:
+    if not path.exists():
+        raise ConfigError(f"No config at {path}. Run `claude-worklog init` first.")
+    try:
+        raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (tomllib.TOMLDecodeError, OSError) as exc:
+        raise ConfigError(f"Cannot read {path}: {exc}") from exc
+
+    device = _check_name("device_name", raw.get("device_name"))
+    if not isinstance(raw.get("store_repo"), str):
+        raise ConfigError("store_repo is required")
+
+    accounts: list[Account] = []
+    for item in raw.get("accounts", []):
+        if not isinstance(item, dict) or not isinstance(item.get("config_dir"), str):
+            raise ConfigError("each [[accounts]] needs name and config_dir")
+        name = _check_name("account name", item.get("name"))
+        accounts.append(Account(name, _expand(item["config_dir"]),
+                                _match_id(name, item.get("match_account_id")),
+                                _match_email(name, item.get("match_email"))))
+    if not accounts:
+        raise ConfigError("configure at least one [[accounts]] block")
+    if len({a.name for a in accounts}) != len(accounts):
+        raise ConfigError("account names must be unique")
+    _check_shared_dirs(accounts)
+
+    col = raw.get("collect", {})
+    rep = raw.get("report", {})
+    cfg = Config(
+        device=device,
+        store_repo=_expand(raw["store_repo"]),
+        accounts=accounts,
+        misc_label=str(col.get("misc_label", "R&D / misc")),
+        include_commits=bool(col.get("include_commits", True)),
+        max_prompts=_int(col, "max_prompts_per_session", 30, 0, 500),
+        max_prompt_chars=_int(col, "max_prompt_chars", 300, 20, 5000),
+        use_ai=bool(rep.get("use_ai", True)),
+        summarizer_account=rep.get("summarizer_account") or accounts[0].name,
+        claude_bin=str(rep.get("claude_bin", "claude")),
+        ai_timeout=_int(rep, "ai_timeout_seconds", 180, 10, 1800),
+        path=path,
+    )
+    if cfg.account(cfg.summarizer_account) is None:
+        raise ConfigError(f"summarizer_account {cfg.summarizer_account!r} is not a configured account")
+    return cfg
+
+
+def example_config() -> str:
+    host = re.sub(r"[^A-Za-z0-9_-]", "-", socket.gethostname())[:40] or "device"
+    return EXAMPLE_CONFIG.format(device=host)
+
+
+# ------------------------------------------------------------------ writing
+def home_relative(p: Path | str) -> str:
+    s, home = str(p), str(Path.home())
+    return "~" + s[len(home):] if s == home or s.startswith(home + "/") else s
+
+
+def under_home(p: Path, allow_home: bool = False) -> bool:
+    home = Path.home().resolve()
+    return (allow_home and p == home) or home in p.parents
+
+
+def dump_config(cfg: Config) -> str:
+    import json
+
+    def q(s: object) -> str:
+        return json.dumps(str(s), ensure_ascii=False)  # JSON strings are valid TOML basic strings
+
+    def b(v: bool) -> str:
+        return "true" if v else "false"
+
+    out = ["# claude-worklog configuration (also editable from the web UI)",
+           f"device_name = {q(cfg.device)}", f"store_repo = {q(home_relative(cfg.store_repo))}", ""]
+    for a in cfg.accounts:
+        out += ["[[accounts]]", f"name = {q(a.name)}", f"config_dir = {q(home_relative(a.config_dir))}"]
+        if a.match_account_id:
+            out.append(f"match_account_id = {q(a.match_account_id)}")
+        if a.match_email:
+            out.append(f"match_email = {q(a.match_email)}")
+        out.append("")
+    out += ["[collect]", f"misc_label = {q(cfg.misc_label)}", f"include_commits = {b(cfg.include_commits)}",
+            f"max_prompts_per_session = {cfg.max_prompts}", f"max_prompt_chars = {cfg.max_prompt_chars}", "",
+            "[report]", f"use_ai = {b(cfg.use_ai)}", f"summarizer_account = {q(cfg.summarizer_account)}",
+            f"claude_bin = {q(cfg.claude_bin)}", f"ai_timeout_seconds = {cfg.ai_timeout}", ""]
+    return "\n".join(out)
+
+
+def save_config(cfg: Config, path: Path = CONFIG_PATH) -> None:
+    """Validate by re-loading from a temp file, back up the old file, then swap atomically."""
+    import shutil
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".toml.tmp")
+    tmp.write_text(dump_config(cfg), encoding="utf-8")
+    tmp.chmod(0o600)
+    try:
+        load_config(tmp)
+    except ConfigError:
+        tmp.unlink(missing_ok=True)
+        raise
+    if path.exists():
+        shutil.copy2(path, path.with_suffix(".toml.bak"))
+    os.replace(tmp, path)

worklog/demo.py

@@ -0,0 +1,214 @@
+"""`claude-worklog demo`: the web UI on a throwaway HOME filled with generated fake data.
+
+Nothing here reads or writes the real home folder. The generator only writes below the
+fake home it is given, and the UI runs as a subprocess whose HOME and XDG_* variables
+point there, so every path the package computes at import time (config, state, data repo,
+Claude folders, ~/.gitconfig) lands inside the temporary folder. systemd calls are
+disabled through services.DEMO_ENV, and the temporary folder is deleted on exit.
+"""
+from __future__ import annotations
+
+import json
+import os
+import random
+import shutil
+import signal
+import subprocess
+import sys
+import tempfile
+from datetime import date, datetime, timedelta
+from pathlib import Path
+
+from .report import project_key
+from .services import DEMO_ENV
+
+DEVICES = ("laptop", "desktop")  # the demo runs as "laptop"; "desktop" plays another synced machine
+MODELS = ("claude-sonnet-5", "claude-opus-5-5", "claude-haiku-4-5")
+
+# name, host, slug (None = outside any git repo), account, weight, prompts, files, commits, summary bullets
+PROJECTS = [
+    {"name": "storefront", "host": "github.com", "slug": "acme-shop/storefront", "account": "work", "weight": 5,
+     "prompts": ["add a coupon field to the checkout form",
+                 "why does the cart badge not update after removing an item?",
+                 "write tests for the price formatter", "make the product grid responsive on small screens",
+                 "refactor the cart store to use a reducer"],
+     "files": ["src/checkout/CouponField.tsx", "src/cart/store.ts", "src/lib/price.ts", "src/lib/price.test.ts",
+               "src/products/Grid.tsx"],
+     "commits": ["Add coupon field to checkout", "Fix stale cart badge count", "Test price formatting edge cases",
+                 "Responsive product grid"],
+     "bullets": ["Added a coupon field to checkout with inline validation.",
+                 "Fixed the cart badge not refreshing after an item was removed.",
+                 "Covered the price formatter with tests for rounding and currencies."]},
+    {"name": "payments-api", "host": "gitlab.com", "slug": "acme-shop/payments-api", "account": "work", "weight": 4,
+     "prompts": ["add idempotency keys to the refund endpoint", "explain this retry loop in the webhook worker",
+                 "the settlement job times out on large batches, find out why", "add a migration for refund reasons"],
+     "files": ["app/refunds/views.py", "app/webhooks/worker.py", "app/settlement/jobs.py",
+               "migrations/0042_refund_reason.py", "tests/test_refunds.py"],
+     "commits": ["Idempotent refunds", "Batch settlement queries", "Add refund reason column"],
+     "bullets": ["Made the refund endpoint idempotent using request keys.",
+                 "Traced settlement timeouts to per-row queries and batched them.",
+                 "Added a migration and tests for refund reasons."]},
+    {"name": "infra", "host": "github.com", "slug": "acme-shop/infra", "account": "work", "weight": 2,
+     "prompts": ["bump the staging node pool and add an autoscaling rule",
+                 "write a runbook for rotating the DB password"],
+     "files": ["terraform/staging/nodes.tf", "docs/runbooks/rotate-db-password.md"],
+     "commits": ["Autoscale staging node pool", "Runbook: DB password rotation"],
+     "bullets": ["Added autoscaling to the staging node pool.", "Wrote a runbook for rotating the database password."]},
+    {"name": "trail-map", "host": "github.com", "slug": "demo-user/trail-map", "account": "personal", "weight": 3,
+     "prompts": ["render GPX tracks on the map with elevation colors", "cache map tiles offline",
+                 "add a dark theme toggle"],
+     "files": ["src/map/tracks.js", "src/map/tiles.js", "src/ui/theme.css"],
+     "commits": ["Color GPX tracks by elevation", "Offline tile cache", "Dark theme"],
+     "bullets": ["Rendered GPX tracks colored by elevation.", "Added an offline cache for map tiles."]},
+    {"name": "R&D / misc", "host": None, "slug": None, "account": "personal", "weight": 2, "folder": "scratch",
+     "prompts": ["compare three ways to debounce a search box", "summarize the tradeoffs of SQLite WAL mode",
+                 "write a quick script to rename photos by date"],
+     "files": ["~/scratch/debounce.js", "~/scratch/rename_photos.py"],
+     "commits": [],
+     "bullets": ["Compared debounce approaches for a search box.", "Read up on SQLite WAL mode tradeoffs."]},
+]
+
+
+def demo_env(home: Path) -> dict[str, str]:
+    """Environment for processes that must only ever see the fake home."""
+    env = {k: v for k, v in os.environ.items() if not k.startswith(("XDG_", "CLAUDE_", "GIT_"))}
+    env.update(HOME=str(home), XDG_CONFIG_HOME=str(home / ".config"), XDG_STATE_HOME=str(home / ".local/state"),
+               XDG_DATA_HOME=str(home / ".local/share"), XDG_CACHE_HOME=str(home / ".cache"),
+               GIT_CONFIG_NOSYSTEM="1", PYTHONUNBUFFERED="1")
+    env[DEMO_ENV] = "1"
+    return env
+
+
+def _config(home: Path, store: Path) -> str:
+    # Absolute paths: the config is also loaded by tests that run with the real HOME.
+    return f"""# claude-worklog DEMO configuration (generated, temporary)
+device_name = "{DEVICES[0]}"
+store_repo = {json.dumps(str(store))}
+
+[[accounts]]
+name = "personal"
+config_dir = {json.dumps(str(home / ".claude"))}
+
+[[accounts]]
+name = "work"
+config_dir = {json.dumps(str(home / ".claude-work"))}
+
+[collect]
+misc_label = "R&D / misc"
+
+[report]
+use_ai = false
+summarizer_account = "personal"
+"""
+
+
+def _record(rng: random.Random, proj: dict, day: date, device: str, n: int, now: datetime) -> dict | None:
+    latest = now.hour - 1 if day == now.date() else 19
+    if latest < 8:
+        return None  # "today" before working hours: no session has happened yet
+    start = datetime(day.year, day.month, day.day, rng.randint(8, latest), rng.randint(0, 59)).astimezone()
+    minutes = rng.randint(12, 150)
+    end = start + timedelta(minutes=minutes)
+    model = rng.choices(MODELS, weights=(6, 2, 2))[0]
+    scale = {"claude-opus-5-5": 1.4, "claude-haiku-4-5": 0.6}.get(model, 1.0)
+    tokens = {"input": int(rng.randint(2_000, 30_000) * scale), "output": int(rng.randint(8_000, 90_000) * scale),
+              "cache_creation": int(rng.randint(40_000, 300_000) * scale),
+              "cache_read": int(rng.randint(400_000, 4_000_000) * scale)}
+    prompts = rng.sample(proj["prompts"], k=min(len(proj["prompts"]), rng.randint(1, 3)))
+    files = sorted(rng.sample(proj["files"], k=min(len(proj["files"]), rng.randint(1, 3))))
+    commits = [{"hash": f"{rng.getrandbits(28):07x}", "subject": s}
+               for s in rng.sample(proj["commits"], k=min(len(proj["commits"]), rng.randint(0, 2)))]
+    branches = ["main"] if not proj["slug"] else sorted({"main", rng.choice(["main", "feature/demo", "fix/demo"])})
+    if proj["slug"]:
+        project = {"kind": "git", "name": proj["name"], "path": f"~/code/{proj['name']}", "branches": branches,
+                   "remote": {"host": proj["host"], "slug": proj["slug"]}}
+    else:
+        project = {"kind": "misc", "name": proj["name"], "path": f"~/{proj['folder']}", "folder": proj["folder"],
+                   "branches": [], "remote": None}
+    return {
+        "schema": 1, "session_id": f"demo-{day:%Y%m%d}-{device}-{n:02d}", "date": day.isoformat(),
+        "account": proj["account"], "device": device, "project": project,
+        "start": start.isoformat(timespec="seconds"), "end": end.isoformat(timespec="seconds"),
+        "span_minutes": minutes, "api_calls": rng.randint(8, 120), "tokens": tokens,
+        "tokens_by_model": {model: tokens}, "prompt_count": len(prompts), "prompts": prompts,
+        "files_touched": files, "tool_calls": {"Read": rng.randint(3, 40), "Edit": rng.randint(1, 20),
+                                               "Bash": rng.randint(0, 15)},
+        "commits": commits if proj["slug"] else [],
+    }
+
+
+def generate(home: Path, days: int = 14, seed: int = 7, now: datetime | None = None) -> Path:
+    """Write a fake HOME: config, empty Claude folders and a data repo with `days` of records.
+
+    Returns the config file path. Only ever writes below `home`.
+    """
+    now = now or datetime.now()
+    rng = random.Random(seed)
+    home.mkdir(parents=True, exist_ok=True)
+    for sub in (".claude/projects", ".claude-work/projects"):
+        (home / sub).mkdir(parents=True, exist_ok=True)
+    store = home / "claude-worklog-data"
+    store.mkdir(exist_ok=True)
+    subprocess.run(["git", "init", "-q", str(store)], check=True, env=demo_env(home), timeout=30)
+    cfg_path = home / ".config" / "claude-worklog" / "config.toml"
+    cfg_path.parent.mkdir(parents=True, exist_ok=True)
+    cfg_path.write_text(_config(home, store), encoding="utf-8")
+    cfg_path.chmod(0o600)
+
+    weights = [p["weight"] for p in PROJECTS]
+    for back in range(days):
+        day = now.date() - timedelta(days=back)
+        weekend = day.weekday() >= 5
+        day_projects: dict[str, dict] = {}
+        for device in DEVICES:
+            count = rng.randint(0, 2) if weekend else rng.randint(1, 4)
+            for n in range(count):
+                proj = PROJECTS[-2 + rng.randint(0, 1)] if weekend else rng.choices(PROJECTS, weights=weights)[0]
+                rec = _record(rng, proj, day, device, n, now)
+                if rec is None:
+                    continue
+                rel = store / "records" / day.isoformat() / device / rec["account"] / f"{rec['session_id']}.json"
+                rel.parent.mkdir(parents=True, exist_ok=True)
+                rel.write_text(json.dumps(rec, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+                day_projects[project_key(rec["project"])] = proj
+        # Past days have finished summaries; today shows raw prompts, as it would before the nightly run.
+        if back > 0 and day_projects:
+            summaries = {key: {"bullets": [f"- {b}" for b in p["bullets"]], "source": "ai"}
+                         for key, p in day_projects.items()}
+            generated = datetime(day.year, day.month, day.day, 23, 30).astimezone()
+            meta = {"date": day.isoformat(), "device": DEVICES[0], "summaries": summaries,
+                    "generated_at": generated.isoformat(timespec="seconds")}
+            out = store / "reports" / day.isoformat() / f"{DEVICES[0]}.json"
+            out.parent.mkdir(parents=True, exist_ok=True)
+            out.write_text(json.dumps(meta, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return cfg_path
+
+
+def run(port: int, seed: int = 7) -> int:
+    """Generate demo data in a temporary folder, serve the UI until Ctrl+C, then delete it."""
+    base = Path(tempfile.mkdtemp(prefix="claude-worklog-demo-"))
+    home = base / "home"
+    try:
+        generate(home, seed=seed)
+        print(f"Demo data (fake, temporary): {base}")
+        print(f"Open http://localhost:{port}  (Ctrl+C to stop; the folder is deleted afterwards)", flush=True)
+        proc = subprocess.Popen([sys.executable, "-m", "worklog.cli", "serve", "--port", str(port)],
+                                env=demo_env(home), cwd=home)
+        old = signal.signal(signal.SIGTERM, _interrupt)  # `kill` cleans up like Ctrl+C does
+        try:
+            return proc.wait()
+        except KeyboardInterrupt:
+            proc.terminate()  # no-op if Ctrl+C already stopped it (the terminal signals both)
+            try:
+                proc.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+            return 0
+        finally:
+            signal.signal(signal.SIGTERM, old)
+    finally:
+        shutil.rmtree(base, ignore_errors=True)
+
+
+def _interrupt(signum, frame):
+    raise KeyboardInterrupt

worklog/hooks.py

@@ -0,0 +1,78 @@
+"""Install/inspect the Claude Code hooks for an account (shared by CLI and web UI).
+
+One command handles both events; it reads `hook_event_name` from stdin:
+  * SessionStart: records which account is logged in (for accounts sharing a folder)
+  * SessionEnd:   starts a background collect
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from datetime import datetime
+
+from .config import Account
+
+HOOK_MARKER = "claude-worklog hook"
+HOOK_EVENTS = ("SessionStart", "SessionEnd")
+
+
+def hook_command() -> str:
+    exe = shutil.which("claude-worklog")
+    return f"{exe} hook" if exe else f"{sys.executable} -m worklog.cli hook  # {HOOK_MARKER}"
+
+
+def _is_ours(command: object) -> bool:
+    return isinstance(command, str) and (HOOK_MARKER in command or "worklog.cli hook" in command)
+
+
+def _events_in(settings: object) -> set[str]:
+    hooks = settings.get("hooks") if isinstance(settings, dict) else None
+    found = set()
+    for event in HOOK_EVENTS:
+        groups = hooks.get(event) if isinstance(hooks, dict) else None
+        for group in groups if isinstance(groups, list) else []:
+            entries = group.get("hooks") if isinstance(group, dict) else None
+            if any(isinstance(h, dict) and _is_ours(h.get("command")) for h in entries or []):
+                found.add(event)
+    return found
+
+
+def installed_events(account: Account) -> set[str]:
+    """Which of our hook events are present in the account's settings.json."""
+    try:
+        return _events_in(json.loads((account.config_dir / "settings.json").read_text(encoding="utf-8")))
+    except (OSError, ValueError):
+        return set()
+
+
+def hook_installed(account: Account) -> bool:
+    return installed_events(account) >= set(HOOK_EVENTS)
+
+
+def install_hook(account: Account) -> tuple[bool, str]:
+    """Idempotently add the missing hooks. Backs up settings.json first. Returns (ok, message)."""
+    path = account.config_dir / "settings.json"
+    try:
+        settings = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {}
+    except (OSError, json.JSONDecodeError) as exc:
+        return False, f"{account.name}: {path} is not valid JSON ({exc}); nothing changed"
+    if not isinstance(settings, dict):
+        return False, f"{account.name}: {path} is not a JSON object; nothing changed"
+    missing = [ev for ev in HOOK_EVENTS if ev not in _events_in(settings)]
+    if not missing:
+        return True, f"{account.name}: hooks already installed"
+    hooks = settings.setdefault("hooks", {})
+    if not isinstance(hooks, dict) or any(not isinstance(hooks.get(ev, []), list) for ev in missing):
+        return False, f"{account.name}: unexpected \"hooks\" layout in {path}; nothing changed"
+    if path.exists():
+        shutil.copy2(path, path.with_name(f"settings.json.bak-{datetime.now():%Y%m%d%H%M%S}"))
+    for ev in missing:
+        hooks.setdefault(ev, []).append({"hooks": [{"type": "command", "command": hook_command()}]})
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+    if path.exists():
+        shutil.copymode(path, tmp)  # keep the original file permissions
+    tmp.replace(path)
+    return True, f"{account.name}: {', '.join(missing)} hook installed in {path}"