sessionpulse 0.1.2__tar.gz → 0.2.0__tar.gz

{sessionpulse-0.1.2/src/sessionpulse.egg-info → sessionpulse-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sessionpulse
-Version: 0.1.2
+Version: 0.2.0
 Summary: A quiet instrument panel for Claude Code: live sessions, usage, and a to-do board that fills itself from your sessions. Local only.
 Author: Vijay Shukla
 License-Expression: MIT
@@ -85,6 +85,7 @@ It reads the files Claude Code already writes under `~/.claude`. **Nothing leave
 
 - **Live sessions:** working or idle, running time, last change, tokens, model. The panel icon shows the count and turns orange while Claude is working.
 - **Follow-ups (optional):** Claude reads each session after 20 quiet minutes and adds what was left open to your to-do list, linked back to the session, with a one-click resume command. A later session that finishes an item closes it automatically.
+- **Why is this here?** Each follow-up keeps a short quote from the session, checked against the transcript; **Why?** shows it in context. The same work showing up in another project is flagged, with **Merge** and **Not the same**.
 - **Board:** every to-do as a card, colour-coded by kind (Decide, Outside work, Waiting on, Checklist, Later), or by status (To do, Doing, Done). Drag and drop, project filter, search.
 - **Your own to-dos too:** add them on the dashboard or with `sessionpulse todo add "…"`.
 - **Usage:** input, output and cache tokens per day, split by model; active hours per day; busiest projects.
@@ -154,6 +155,27 @@ sessionpulse followups    # read the last 30 days now instead of waiting
 
 Check everything with `sessionpulse doctor`. Remove it with `sessionpulse uninstall` (your data stays) and `pipx uninstall sessionpulse`.
 
+## GNOME extension
+
+A native top-bar indicator for GNOME Shell 45 to 48, as an alternative to the AppIndicator panel icon. It shows the same thing: the number of open sessions, orange while one is working, plus a menu with each session, today's totals, and links to the dashboard and the to-do board.
+
+The extension only reads `~/.local/share/sessionpulse/status.json` ([format](https://github.com/vijayshuklaHL/sessionpulse/blob/main/docs/status-json.md)), which `sessionpulse daemon` writes, so the app has to be installed too:
+
+```sh
+pipx install sessionpulse
+sessionpulse install --daemon   # hooks, plus the daemon (no icon) at login
+sessionpulse daemon &           # start it now
+```
+
+Then install the extension. It isn't on extensions.gnome.org yet, so install it from a clone of this repo:
+
+```sh
+gnome-extension/pack.sh
+gnome-extensions install --force gnome-extension/dist/sessionpulse@vijayshuklaHL.github.io.shell-extension.zip
+```
+
+Log out and back in (on X11 you can press Alt+F2 and type `r` instead), then run `gnome-extensions enable sessionpulse@vijayshuklaHL.github.io`. If you used the panel icon before, stop it: run `sessionpulse install --daemon` again so login starts the daemon instead of the tray.
+
 ## Commands
 
 | Command | What it does |
@@ -162,10 +184,14 @@ Check everything with `sessionpulse doctor`. Remove it with `sessionpulse uninst
 | `sessionpulse uninstall` | Removes exactly those hooks and the autostart entry. Your data stays. |
 | `sessionpulse tray` | Panel icon and dashboard server |
 | `sessionpulse serve` | Dashboard server only |
+| `sessionpulse daemon` | Dashboard server plus `status.json` for panel widgets such as the GNOME extension, no icon (`install --daemon` starts it at login) |
 | `sessionpulse open` | Opens the dashboard in your browser, signed in (add `#board` to the address for the board) |
 | `sessionpulse doctor` | Checks the setup and warns if Claude Code's file formats look different |
 | `sessionpulse todo [add TEXT -p PROJECT \| done ID \| undo ID \| delete ID \| list-done]` | Your to-do list from the terminal |
+| `sessionpulse todo export [--format md\|csv\|json] [-p PROJECT] [--status open\|all]` | Prints the list as Markdown (grouped by project), CSV or JSON; the board's Export menu downloads the same ([fields](https://github.com/vijayshuklaHL/sessionpulse/blob/main/docs/todos-json.md)) |
 | `sessionpulse followups [--days N] [--session ID] [--now] [--again]` | Read recent sessions now and add their open follow-ups |
+| `sessionpulse followups status` | What follow-ups used (calls, tokens, cost), results per kind, and sessions that failed |
+| `sessionpulse dedupe [-p PROJECT] [--across] [--apply]` | Finds open to-dos that are the same work reworded (`--across`: in different projects); `--apply` archives the copies |
 | `sessionpulse snapshot` | Prints the dashboard data as JSON |
 
 ## Settings

{sessionpulse-0.1.2 → sessionpulse-0.2.0}/README.md

@@ -57,6 +57,7 @@ It reads the files Claude Code already writes under `~/.claude`. **Nothing leave
 
 - **Live sessions:** working or idle, running time, last change, tokens, model. The panel icon shows the count and turns orange while Claude is working.
 - **Follow-ups (optional):** Claude reads each session after 20 quiet minutes and adds what was left open to your to-do list, linked back to the session, with a one-click resume command. A later session that finishes an item closes it automatically.
+- **Why is this here?** Each follow-up keeps a short quote from the session, checked against the transcript; **Why?** shows it in context. The same work showing up in another project is flagged, with **Merge** and **Not the same**.
 - **Board:** every to-do as a card, colour-coded by kind (Decide, Outside work, Waiting on, Checklist, Later), or by status (To do, Doing, Done). Drag and drop, project filter, search.
 - **Your own to-dos too:** add them on the dashboard or with `sessionpulse todo add "…"`.
 - **Usage:** input, output and cache tokens per day, split by model; active hours per day; busiest projects.
@@ -126,6 +127,27 @@ sessionpulse followups    # read the last 30 days now instead of waiting
 
 Check everything with `sessionpulse doctor`. Remove it with `sessionpulse uninstall` (your data stays) and `pipx uninstall sessionpulse`.
 
+## GNOME extension
+
+A native top-bar indicator for GNOME Shell 45 to 48, as an alternative to the AppIndicator panel icon. It shows the same thing: the number of open sessions, orange while one is working, plus a menu with each session, today's totals, and links to the dashboard and the to-do board.
+
+The extension only reads `~/.local/share/sessionpulse/status.json` ([format](https://github.com/vijayshuklaHL/sessionpulse/blob/main/docs/status-json.md)), which `sessionpulse daemon` writes, so the app has to be installed too:
+
+```sh
+pipx install sessionpulse
+sessionpulse install --daemon   # hooks, plus the daemon (no icon) at login
+sessionpulse daemon &           # start it now
+```
+
+Then install the extension. It isn't on extensions.gnome.org yet, so install it from a clone of this repo:
+
+```sh
+gnome-extension/pack.sh
+gnome-extensions install --force gnome-extension/dist/sessionpulse@vijayshuklaHL.github.io.shell-extension.zip
+```
+
+Log out and back in (on X11 you can press Alt+F2 and type `r` instead), then run `gnome-extensions enable sessionpulse@vijayshuklaHL.github.io`. If you used the panel icon before, stop it: run `sessionpulse install --daemon` again so login starts the daemon instead of the tray.
+
 ## Commands
 
 | Command | What it does |
@@ -134,10 +156,14 @@ Check everything with `sessionpulse doctor`. Remove it with `sessionpulse uninst
 | `sessionpulse uninstall` | Removes exactly those hooks and the autostart entry. Your data stays. |
 | `sessionpulse tray` | Panel icon and dashboard server |
 | `sessionpulse serve` | Dashboard server only |
+| `sessionpulse daemon` | Dashboard server plus `status.json` for panel widgets such as the GNOME extension, no icon (`install --daemon` starts it at login) |
 | `sessionpulse open` | Opens the dashboard in your browser, signed in (add `#board` to the address for the board) |
 | `sessionpulse doctor` | Checks the setup and warns if Claude Code's file formats look different |
 | `sessionpulse todo [add TEXT -p PROJECT \| done ID \| undo ID \| delete ID \| list-done]` | Your to-do list from the terminal |
+| `sessionpulse todo export [--format md\|csv\|json] [-p PROJECT] [--status open\|all]` | Prints the list as Markdown (grouped by project), CSV or JSON; the board's Export menu downloads the same ([fields](https://github.com/vijayshuklaHL/sessionpulse/blob/main/docs/todos-json.md)) |
 | `sessionpulse followups [--days N] [--session ID] [--now] [--again]` | Read recent sessions now and add their open follow-ups |
+| `sessionpulse followups status` | What follow-ups used (calls, tokens, cost), results per kind, and sessions that failed |
+| `sessionpulse dedupe [-p PROJECT] [--across] [--apply]` | Finds open to-dos that are the same work reworded (`--across`: in different projects); `--apply` archives the copies |
 | `sessionpulse snapshot` | Prints the dashboard data as JSON |
 
 ## Settings

{sessionpulse-0.1.2 → sessionpulse-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sessionpulse"
-version = "0.1.2"
+version = "0.2.0"
 description = "A quiet instrument panel for Claude Code: live sessions, usage, and a to-do board that fills itself from your sessions. Local only."
 readme = "README.md"
 license = "MIT"

{sessionpulse-0.1.2 → sessionpulse-0.2.0}/src/sessionpulse/__init__.py

@@ -1,3 +1,3 @@
 """Session Pulse: a local dashboard and panel icon for Claude Code sessions."""
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"

sessionpulse-0.2.0/src/sessionpulse/cli.py

@@ -0,0 +1,351 @@
+"""Command line: sessionpulse <command>."""
+import argparse
+import getpass
+import json
+import os
+import signal
+import socket
+import subprocess
+import sys
+import threading
+import webbrowser
+from collections import Counter
+
+from . import __version__, config, followups, hook, install, reader, server, status, todos, tray
+
+
+def headless():
+    """True on a Linux/BSD box with no desktop session, e.g. a server you reach over SSH."""
+    return (sys.platform not in ("darwin", "win32")
+            and not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"))
+
+
+def remote_hint(cfg):
+    """How to reach the dashboard from another computer through an SSH tunnel."""
+    host = f"{getpass.getuser()}@{socket.gethostname()}"
+    return (f"No desktop here, so open it from your own computer through an SSH tunnel:\n"
+            f"  ssh -N -L {cfg.port}:127.0.0.1:{cfg.port} {host}\n"
+            f"then browse to:\n  {server.open_url(cfg)}\n"
+            f"(Use the address you normally ssh to. If port {cfg.port} is busy on your computer, "
+            f"use another local port, e.g. -L 18765:127.0.0.1:{cfg.port}, and change it in the link.)")
+
+
+def cmd_serve(cfg, args):
+    try:
+        srv = server.make_server(cfg)
+    except OSError as exc:
+        raise SystemExit(f"Can't serve on port {cfg.port}: {exc.strerror or exc}. Something else is using it "
+                         f"(another `sessionpulse serve`/`tray`?); stop that, or set `port` in {config.CONFIG_FILE}.")
+    followups.start_worker(cfg)
+    print(f"Session Pulse on {cfg.url}\n" + (remote_hint(cfg) if headless() else "Open it with: sessionpulse open"),
+          flush=True)
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        pass
+
+
+def cmd_daemon(cfg, args):
+    """Dashboard server + follow-ups + status.json, no icon: for the GNOME extension."""
+    try:
+        srv = server.make_server(cfg)
+        threading.Thread(target=srv.serve_forever, daemon=True).start()
+        followups.start_worker(cfg)
+        print(f"Session Pulse on {cfg.url}", flush=True)
+    except OSError:
+        print(f"Port {cfg.port} is already in use (another `sessionpulse serve`/`tray`?); "
+              "writing status.json only.", flush=True)
+    print(f"Writing {status.path(cfg)} every {status.INTERVAL}s", flush=True)
+    stop = threading.Event()
+    for sig in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP):
+        signal.signal(sig, lambda *_: stop.set())
+    status.run(cfg, stop, on_error=lambda exc: print(f"status.json not written: {exc}",
+                                                    file=sys.stderr, flush=True))
+
+
+def cmd_tray(cfg, args):
+    tray.run(cfg)
+
+
+def cmd_open(cfg, args):
+    if headless() or not webbrowser.open(server.open_url(cfg)):
+        print(remote_hint(cfg) if headless() else f"Couldn't start a browser. Open:\n  {server.open_url(cfg)}")
+    with socket.socket() as s:
+        if s.connect_ex(("127.0.0.1", cfg.port)) != 0:
+            print("Note: the dashboard isn't running. Start it with `sessionpulse serve` (or `sessionpulse tray`).")
+
+
+def cmd_hook(cfg, args):
+    return hook.run()
+
+
+def cmd_install(cfg, args):
+    try:
+        changed = install.install_hooks(cfg)
+    except install.SettingsError as exc:
+        sys.exit(f"error: {exc}")
+    print(("Added" if changed else "Already present:") +
+          f" SessionStart/SessionEnd hooks in {cfg.claude / 'settings.json'}")
+    if args.no_autostart:
+        return
+    if args.daemon:
+        print(f"Background daemon will start at login ({install.enable_autostart('daemon')}).")
+        print("Start it now with: sessionpulse daemon &")
+        return
+    missing = tray.available()
+    if missing:
+        print(f"Skipped login autostart: {missing}\nYou can still run: sessionpulse serve")
+        return
+    print(f"Panel icon will start at login ({install.enable_autostart()}).")
+    print("Start it now with: sessionpulse tray &")
+
+
+def cmd_uninstall(cfg, args):
+    try:
+        changed = install.uninstall_hooks(cfg)
+    except install.SettingsError as exc:
+        sys.exit(f"error: {exc}")
+    print("Removed Session Pulse hooks." if changed else "No Session Pulse hooks were installed.")
+    if install.disable_autostart():
+        print("Removed login autostart.")
+    print(f"Your data is kept in {cfg.data}; delete that folder to remove it.")
+
+
+def cmd_doctor(cfg, args):
+    ok = True
+
+    def line(good, text):
+        nonlocal ok
+        ok &= bool(good)
+        print(f"  {'ok ' if good else 'FIX'}  {text}")
+
+    print(f"Session Pulse {__version__}")
+    line(cfg.claude.is_dir(), f"Claude Code folder: {cfg.claude}")
+    line((cfg.claude / "sessions").is_dir(), "live-session files (sessions/)")
+    snap = reader.snapshot(cfg)
+    h = snap["health"]
+    line(h["files"] > 0, f"{h['files']} transcripts, {len(snap['sessions'])} sessions, "
+                         f"newest Claude Code {h['newest_cli'] or '?'}")
+    try:
+        inst = install.hooks_installed(cfg)
+        line(inst == set(install.EVENTS), "start/exit hooks installed" if inst == set(install.EVENTS)
+             else "start/exit hooks missing: run `sessionpulse install`")
+    except install.SettingsError as exc:
+        line(False, str(exc))
+    if headless():
+        print("  --   no desktop session: the panel icon and login autostart don't apply here. "
+              "Run `sessionpulse serve` (see \"On a server\" in the README) and use `sessionpulse open` "
+              "for the SSH tunnel link.")
+    else:
+        missing = tray.available()
+        print(f"  {'ok ' if not missing else '-- '}  {'panel icon available' if not missing else missing}")
+    with socket.socket() as s:
+        busy = s.connect_ex(("127.0.0.1", cfg.port)) == 0
+    print(f"  {'ok ' if busy else '-- '}  dashboard {'running' if busy else 'not running'} on {cfg.url}"
+          + ("" if busy else ": start it with `sessionpulse serve`"))
+    a = status.age(cfg)
+    if a is not None:
+        fresh = a < status.INTERVAL * 3
+        print(f"  {'ok ' if fresh else '-- '}  status.json {'updated' if fresh else 'stale, last updated'} "
+              f"{int(a)}s ago{'' if fresh else ': is `sessionpulse daemon` running?'}")
+    bad = followups.failing(cfg)
+    if bad:
+        sid, e = bad[0]
+        print(f"  --   {len(bad)} session(s) failed when read for follow-ups; the latest error: "
+              f"{e.get('last_error')}. See `sessionpulse followups status`.")
+    week = followups.usage_totals(cfg, 7)
+    if week["calls"]:
+        print(f"  ok   follow-ups used {week['calls']} model calls, {tokens(week['tokens'])} tokens in the last 7 days")
+    for w in h["warnings"]:
+        line(False, w)
+    return 0 if ok else 1
+
+
+def tokens(n):
+    return f"{n / 1e6:.1f}M" if n >= 1e6 else f"{n / 1e3:.0f}k" if n >= 1e3 else str(n)
+
+
+def cmd_snapshot(cfg, args):
+    json.dump(reader.snapshot(cfg), sys.stdout, indent=1)
+
+
+def cmd_todo(cfg, args):
+    if args.action == "export":
+        try:
+            sys.stdout.write(todos.export(todos.load(cfg), args.format, args.project, args.status))
+        except ValueError as exc:
+            sys.exit(f"error: {exc}")
+        return
+    try:
+        if args.action == "add":
+            todos.apply(cfg, {"op": "add", "text": " ".join(args.text), "project": args.project})
+        elif args.action in ("done", "undo", "delete"):
+            for i in args.text:
+                todos.apply(cfg, {"op": args.action, "id": i})
+    except ValueError as exc:
+        sys.exit(f"error: {exc}")
+    items = todos.load(cfg)
+    want = (lambda i: i["done_at"]) if args.action == "list-done" else todos.is_open
+    show = [i for i in items if want(i)]
+    for i in show:
+        tag = f"  [{i['project']}]" if i.get("project") else ""
+        when = f"  done {i['done_at'][:10]}" if i["done_at"] else ""
+        print(f"{i['id']}  {i['text']}{tag}{when}")
+    parked = [i for i in items if not i["done_at"] and i.get("status") in todos.STATUSES]
+    if parked and args.action != "list-done":
+        held = sum(i["status"] == "hold" for i in parked)
+        print(f"({held} on hold, {len(parked) - held} archived; see the dashboard board)")
+    if not show:
+        print("Nothing here." if args.action == "list-done" else "No open to-dos.")
+
+
+def followups_status(cfg):
+    print(f"Follow-ups are {'on' if cfg.followups else 'off (add `followups = true` to config.toml)'}; "
+          f"model {cfg.followups_model}.")
+    st = followups.load_state(cfg)
+    read = [e for e in st.values() if isinstance(e, dict) and e.get("at")]
+    print(f"Sessions read: {len(read)}, adding {sum(e.get('added') or 0 for e in read)} "
+          f"and closing {sum(e.get('closed') or 0 for e in read)} to-dos.")
+    print("Model use (the cost is what the API would charge; on a subscription it counts toward your limits):")
+    for label, days in (("today", 1), ("7 days", 7), ("30 days", 30)):
+        u = followups.usage_totals(cfg, days)
+        print(f"  {label:8} {u['calls']:4} calls  {tokens(u['tokens']):>6} tokens "
+              f"({tokens(u['output_tokens'])} written)  ${u['cost_usd']:.2f}")
+    kinds = todos.kind_stats(cfg)
+    if kinds:
+        print("By kind (dismissed items count as added; \"noise\" = dismissed as not useful):")
+        print(f"  {'':10} {'added':>6} {'open':>6} {'done':>6} {'parked':>6} {'noise':>6} {'other':>6}")
+        for k in (*todos.KINDS, "unknown"):
+            if k in kinds:
+                r = kinds[k]
+                print(f"  {k:10} " + " ".join(f"{r[c]:>6}" for c in ("added", "open", "done", "parked",
+                                                                       "not_useful", "dismissed")))
+    bad = followups.failing(cfg)
+    if not bad:
+        print("No session is failing.")
+        return
+    print(f"{len(bad)} session(s) failed when last read:")
+    for sid, e in bad:
+        when = f"next try after {e['next_try'][:16].replace('T', ' ')}" if e.get("next_try") else \
+            "waiting until the session grows"
+        print(f"  {sid[:8]}  {e.get('project') or '?'}: {e['fails']}x, {when}\n            {e.get('last_error')}")
+    print("Retry one now with `sessionpulse followups --session <id>`.")
+
+
+def cmd_followups(cfg, args):
+    if args.action == "status":
+        return followups_status(cfg)
+    if not followups.claude_bin(cfg):
+        sys.exit("error: the `claude` command was not found; set claude_command in config.toml")
+    try:
+        n, added, closed = followups.scan(cfg, days=args.days, idle_minutes=0 if args.now else None,
+                                          session=args.session, force=args.again,
+                                          log=lambda m: print(m, flush=True))
+    except (RuntimeError, OSError, ValueError) as exc:
+        sys.exit(f"error: {exc}")
+    print(f"Read {n} session(s): {added} follow-up(s) added, {closed} closed.")
+    if not cfg.followups:
+        print("Tip: add `followups = true` to ~/.config/sessionpulse/config.toml to do this automatically.")
+
+
+def cmd_dedupe(cfg, args):
+    if not followups.claude_bin(cfg):
+        sys.exit("error: the `claude` command was not found; set claude_command in config.toml")
+    if args.across:
+        return dedupe_across(cfg, args)
+    items = todos.load(cfg)
+    counts = Counter(i.get("project") or "" for i in items if todos.is_open(i))
+    projects = [args.project] if args.project is not None else [p for p, n in counts.items() if n > 1]
+    text = {i["id"]: i["text"] for i in items}
+    total = 0
+    for project in projects:
+        try:
+            groups = followups.find_duplicates(cfg, project)
+        except (RuntimeError, OSError, ValueError, subprocess.TimeoutExpired) as exc:
+            print(f"{project or '(no project)'}: skipped, {exc}", flush=True)
+            continue
+        if not groups:
+            continue
+        print(f"\n{project or '(no project)'}", flush=True)
+        for g in groups:
+            print("  same:")
+            for x in g:
+                print(f"    {x}  {text.get(x, '')}")
+        if args.apply:
+            n = todos.merge_duplicates(cfg, groups)
+        else:
+            n = sum(len(g) - 1 for g in groups)
+        total += n
+    if args.apply:
+        print(f"\nArchived {total} duplicate(s); each keeps `duplicate_of` pointing at the one kept.")
+    else:
+        print(f"\n{total} duplicate(s) found. Run again with --apply to archive them, keeping the newest.")
+
+
+def dedupe_across(cfg, args):
+    pairs = followups.pairs_across(cfg)
+    print(f"{len(pairs)} pair(s) across projects look alike; asking Claude which are the same work…", flush=True)
+    if not pairs:
+        return
+    try:
+        groups = followups.find_duplicates_across(cfg, pairs)
+    except (RuntimeError, OSError, ValueError, subprocess.TimeoutExpired) as exc:
+        sys.exit(f"error: {exc}")
+    by_id = {i["id"]: i for i in todos.load(cfg)}
+    for g in groups:
+        print("\n  same:")
+        for x in g:
+            i = by_id.get(x, {})
+            print(f"    {x}  {i.get('text', '')}  ({i.get('project') or 'no project'})")
+    if args.apply:
+        n = todos.merge_duplicates(cfg, groups, link=True)
+        print(f"\nArchived {n} duplicate(s), keeping the newest (or the one in progress). Their projects now count "
+              "as related, so follow-ups in one can close work listed in the other.")
+    else:
+        print(f"\n{sum(len(g) - 1 for g in groups)} duplicate(s) found. Run again with --apply to archive them, "
+              "keeping the newest, and link their projects.")
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="sessionpulse", description=__doc__)
+    p.add_argument("--version", action="version", version=f"sessionpulse {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    i = sub.add_parser("install", help="add Claude Code hooks and login autostart")
+    i.add_argument("--no-autostart", action="store_true", help="only add the hooks")
+    i.add_argument("--daemon", action="store_true",
+                   help="autostart the background daemon (for the GNOME extension) instead of the panel icon")
+    sub.add_parser("uninstall", help="remove the hooks and autostart (keeps your data)")
+    sub.add_parser("tray", help="panel icon + dashboard server")
+    sub.add_parser("serve", help="dashboard server only")
+    sub.add_parser("daemon", help="dashboard server + status.json for the GNOME extension, no icon")
+    sub.add_parser("open", help="open the dashboard in your browser")
+    sub.add_parser("doctor", help="check the setup and data formats")
+    sub.add_parser("snapshot", help="print the dashboard data as JSON")
+    t = sub.add_parser("todo", help="your to-do list: add, done, undo, delete, list, list-done, export")
+    t.add_argument("action", nargs="?", default="list",
+                   choices=["list", "list-done", "add", "done", "undo", "delete", "export"])
+    t.add_argument("text", nargs="*", help="the to-do text (add) or item ids (done/undo/delete)")
+    t.add_argument("-p", "--project", help="tag the new to-do with a project (export: only this project)")
+    t.add_argument("--format", choices=todos.FORMATS, default="md", help="export: md (default), csv or json")
+    t.add_argument("--status", choices=["open", "all"], default="open",
+                   help="export: open to-dos (default) or all, including done, on hold and archived")
+    f = sub.add_parser("followups", help="pick open follow-ups out of recent sessions with Claude")
+    f.add_argument("action", nargs="?", default="run", choices=["run", "status"],
+                   help="run (default), or status: model use and sessions that failed")
+    f.add_argument("--days", type=int, help="look back this many days (default: followups_days)")
+    f.add_argument("--session", help="only this session id (or its first characters)")
+    f.add_argument("--now", action="store_true", help="include sessions that are still active")
+    f.add_argument("--again", action="store_true", help="re-read sessions already read")
+    d = sub.add_parser("dedupe", help="find open to-dos that are the same work reworded, with Claude")
+    d.add_argument("-p", "--project", help="only this project (default: every project)")
+    d.add_argument("--apply", action="store_true", help="archive the copies (default: only list them)")
+    d.add_argument("--across", action="store_true",
+                   help="look for the same work listed in different projects (one model call per 40 likely pairs)")
+    sub.add_parser("hook", help=argparse.SUPPRESS)
+    args = p.parse_args(argv)
+    cfg = config.load()
+    return globals()[f"cmd_{args.cmd}"](cfg, args) or 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())