chatdeck 0.1.0__py3-none-any.whl

chatdeck/__init__.py

@@ -0,0 +1,2 @@
+"""chatdeck: a local dashboard for Claude Code chats."""
+__version__ = "0.1.0"

chatdeck/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

chatdeck/autostart.py

@@ -0,0 +1,91 @@
+"""Starting chatdeck at login.
+
+WSL: a "chatdeck" shortcut in the Windows Startup folder runs the launcher (server in WSL, then
+the corner bubble and tray icon); another in the Start menu also opens the dashboard.
+macOS: a LaunchAgent. Linux: a systemd user service, or an XDG autostart entry without systemd."""
+import os, shutil, subprocess
+
+from . import config, desktop, hooks, terminals
+
+LABEL = "io.github.chatdeck"
+MAC_PLIST = os.path.expanduser(f"~/Library/LaunchAgents/{LABEL}.plist")
+SYSTEMD_UNIT = os.path.expanduser("~/.config/systemd/user/chatdeck.service")
+XDG_ENTRY = os.path.expanduser("~/.config/autostart/chatdeck.desktop")
+
+
+def _serve_args(port):
+    """The command line that runs the server, as a list (for launchd/systemd)."""
+    exe = shutil.which("chatdeck")
+    if exe: return [exe, "serve", "--port", str(port)]
+    return None   # running from a clone without the installed command: use the shell form
+
+
+def _shell_cmd(port):
+    return f"{hooks.command()} serve --port {port}"
+
+
+def enable(port, hotkey=""):
+    k = terminals.kind()
+    if k == "wsl":
+        distro = os.environ.get("WSL_DISTRO_NAME") or "Ubuntu"
+        folder = desktop.install_windows_files(port, distro, hooks.command())
+        f = desktop.win_folders()
+        desktop.shortcut(f["startup"] + "\\chatdeck.lnk", folder)
+        desktop.shortcut(f["programs"] + "\\chatdeck.lnk", folder, "-Open", hotkey)
+        return [f"Windows Startup: starts chatdeck and the corner button at login",
+                f"Start menu: \"chatdeck\" opens the dashboard" + (f" ({hotkey})" if hotkey else "")]
+    if k == "mac":
+        args = _serve_args(port) or ["/bin/sh", "-lc", _shell_cmd(port)]
+        items = "".join(f"<string>{a}</string>" for a in args)
+        os.makedirs(os.path.dirname(MAC_PLIST), exist_ok=True)
+        with open(MAC_PLIST, "w") as fh:
+            fh.write(f'<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" '
+                     f'"http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>'
+                     f"<key>Label</key><string>{LABEL}</string><key>ProgramArguments</key><array>{items}</array>"
+                     f"<key>RunAtLoad</key><true/><key>KeepAlive</key><true/>"
+                     f"<key>StandardErrorPath</key><string>{config.DATA}/server.log</string></dict></plist>\n")
+        subprocess.run(["launchctl", "bootout", f"gui/{os.getuid()}/{LABEL}"], capture_output=True)
+        subprocess.run(["launchctl", "bootstrap", f"gui/{os.getuid()}", MAC_PLIST], capture_output=True)
+        return ["LaunchAgent: chatdeck starts at login"]
+    if k == "linux":
+        if shutil.which("systemctl") and subprocess.run(["systemctl", "--user", "is-system-running"], capture_output=True).returncode in (0, 1):
+            exec_line = " ".join(_serve_args(port) or ["/bin/sh", "-lc", f"'{_shell_cmd(port)}'"])
+            os.makedirs(os.path.dirname(SYSTEMD_UNIT), exist_ok=True)
+            with open(SYSTEMD_UNIT, "w") as fh:
+                fh.write(f"[Unit]\nDescription=chatdeck dashboard for Claude Code\n\n[Service]\nExecStart={exec_line}\n"
+                         f"Restart=on-failure\n\n[Install]\nWantedBy=default.target\n")
+            subprocess.run(["systemctl", "--user", "daemon-reload"], capture_output=True)
+            subprocess.run(["systemctl", "--user", "enable", "--now", "chatdeck.service"], capture_output=True)
+            return ["systemd user service: chatdeck starts at login"]
+        os.makedirs(os.path.dirname(XDG_ENTRY), exist_ok=True)
+        with open(XDG_ENTRY, "w") as fh:
+            fh.write(f"[Desktop Entry]\nType=Application\nName=chatdeck\nExec=/bin/sh -lc '{_shell_cmd(port)}'\n"
+                     f"X-GNOME-Autostart-enabled=true\n")
+        return ["desktop autostart entry: chatdeck starts when you log in"]
+    raise SystemExit("Starting at login isn't supported on this system.")
+
+
+def disable():
+    k = terminals.kind(); done = []
+    if k == "wsl":
+        f = desktop.win_folders()
+        for lnk in (f["startup"] + "\\chatdeck.lnk", f["programs"] + "\\chatdeck.lnk"):
+            p = desktop.to_wsl(lnk)
+            if os.path.exists(p): os.remove(p); done.append(f"removed {lnk}")
+    elif k == "mac":
+        subprocess.run(["launchctl", "bootout", f"gui/{os.getuid()}/{LABEL}"], capture_output=True)
+        if os.path.exists(MAC_PLIST): os.remove(MAC_PLIST); done.append("removed the LaunchAgent")
+    elif k == "linux":
+        if os.path.exists(SYSTEMD_UNIT):
+            subprocess.run(["systemctl", "--user", "disable", "--now", "chatdeck.service"], capture_output=True)
+            os.remove(SYSTEMD_UNIT); done.append("removed the systemd user service")
+        if os.path.exists(XDG_ENTRY): os.remove(XDG_ENTRY); done.append("removed the autostart entry")
+    return done
+
+
+def status():
+    k = terminals.kind()
+    if k == "wsl": return os.path.exists(desktop.to_wsl(desktop.win_folders()["startup"] + "\\chatdeck.lnk"))
+    if k == "mac": return os.path.exists(MAC_PLIST)
+    if k == "linux": return os.path.exists(SYSTEMD_UNIT) or os.path.exists(XDG_ENTRY)
+    return False

chatdeck/cli.py

@@ -0,0 +1,152 @@
+"""chatdeck command line.
+
+  chatdeck                  start the dashboard (in the background) and open it
+  chatdeck serve            run the server in the foreground (what autostart uses)
+  chatdeck stop             stop a background server
+  chatdeck setup            add the Claude Code hooks for plan limits and "waiting for you"
+  chatdeck autostart on|off start chatdeck at login, or stop doing that
+  chatdeck uninstall        remove the hooks and autostart
+  chatdeck demo             try it with made-up chats (nothing real is read or changed)
+  chatdeck bubble           Windows (WSL): start the corner button and tray icon
+  chatdeck hook ...         used by Claude Code itself"""
+import argparse, os, signal, subprocess, sys, time, urllib.request
+
+from . import __version__, config, hooks
+
+
+def _up(port):
+    try:
+        with urllib.request.urlopen(f"http://127.0.0.1:{port}/", timeout=2) as r:
+            return b"<title>chatdeck</title>" in r.read(4096)
+    except OSError:
+        return False
+
+
+def _start_background(port):
+    os.makedirs(config.DATA, exist_ok=True)
+    log = open(os.path.join(config.DATA, "server.log"), "ab")
+    env = dict(os.environ, PYTHONPATH=os.pathsep.join(filter(None, [os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+                                                                    os.environ.get("PYTHONPATH")])))
+    subprocess.Popen([sys.executable, "-m", "chatdeck", "serve", "--port", str(port)], stdout=log, stderr=log,
+                     stdin=subprocess.DEVNULL, start_new_session=True, env=env)
+    for _ in range(40):
+        if _up(port): return True
+        time.sleep(0.25)
+    return False
+
+
+def cmd_open(a):
+    from . import desktop
+    if not _up(a.port):
+        print(f"Starting chatdeck on http://127.0.0.1:{a.port} ...")
+        if not _start_background(a.port):
+            sys.exit(f"chatdeck didn't start - see {os.path.join(config.DATA, 'server.log')}")
+    if not a.no_open: desktop.open_dashboard(f"http://127.0.0.1:{a.port}/")
+    print(f"chatdeck is running at http://127.0.0.1:{a.port}")
+    if not os.path.exists(os.path.join(config.DATA, "status")) and "statusline_command" not in config.load():
+        print("Tip: run `chatdeck setup` so it can show your plan limits and which chats are waiting for you.")
+
+
+def cmd_serve(a):
+    from . import server
+    if _up(a.port): sys.exit(f"chatdeck is already running on port {a.port}.")
+    print(f"chatdeck on http://127.0.0.1:{a.port}  (Ctrl+C to stop)", flush=True)
+    try:
+        server.serve(a.port)
+    except OSError as e:
+        sys.exit(f"Can't use port {a.port}: {e.strerror}. Pick another with --port.")
+    except KeyboardInterrupt:
+        pass
+
+
+def cmd_stop(a):
+    try:
+        with open(os.path.join(config.DATA, "server.pid")) as f: pid = int(f.read())
+        os.kill(pid, signal.SIGTERM); print("Stopped chatdeck.")
+    except (OSError, ValueError):
+        print("chatdeck isn't running in the background.")
+
+
+def cmd_setup(a):
+    for line in hooks.install(): print("  " + line)
+    print(f"Done. Your previous settings were backed up to {os.path.join(config.DATA, 'backups')}.")
+    print("New and restarted Claude Code sessions pick this up.")
+
+
+def cmd_uninstall(a):
+    done = hooks.uninstall()
+    try:
+        from . import autostart
+        done += autostart.disable()
+    except SystemExit:
+        pass
+    for line in done or ["nothing to remove"]: print("  " + line)
+
+
+def cmd_autostart(a):
+    from . import autostart
+    if a.state == "on":
+        cfg = config.load(); cfg["port"] = a.port; config.save(cfg)
+        for line in autostart.enable(a.port, a.hotkey): print("  " + line)
+    elif a.state == "off":
+        for line in autostart.disable() or ["it wasn't set to start at login"]: print("  " + line)
+    else:
+        print("on" if autostart.status() else "off")
+
+
+def cmd_bubble(a):
+    from . import desktop, terminals
+    if terminals.kind() != "wsl": sys.exit("The corner button is Windows-only for now (run chatdeck from WSL).")
+    desktop.start_bubble(a.port)
+
+
+def cmd_demo(a):
+    import shutil, tempfile
+    from . import demo, desktop
+    root = tempfile.mkdtemp(prefix="chatdeck-demo-")
+    try:
+        env = dict(os.environ, HOME=root, CHATDECK_DIR=demo.build(root), CHATDECK_DEMO="1",
+                   PYTHONPATH=os.pathsep.join(filter(None, [os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+                                                            os.environ.get("PYTHONPATH")])))
+        srv = subprocess.Popen([sys.executable, "-m", "chatdeck", "serve", "--port", str(a.port)], env=env)
+        url = f"http://127.0.0.1:{a.port}/"
+        for _ in range(40):
+            if _up(a.port) or srv.poll() is not None: break
+            time.sleep(0.25)
+        if not a.no_open and srv.poll() is None: desktop.open_dashboard(url)
+        srv.wait()
+    except KeyboardInterrupt:
+        srv.wait()
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def cmd_hook(a):
+    if a.name == "statusline": hooks.statusline()
+    elif a.name == "waiting": hooks.waiting()
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="chatdeck", description="A local dashboard for your Claude Code chats.")
+    p.add_argument("--version", action="version", version=f"chatdeck {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+    def port_arg(sp): sp.add_argument("--port", type=int, default=config.port(), help=f"default {config.port()}")
+    o = sub.add_parser("open", help="start the dashboard if needed and open it (the default)")
+    port_arg(o); o.add_argument("--no-open", action="store_true", help="start it but don't open a window")
+    port_arg(sub.add_parser("serve", help="run the server in the foreground"))
+    sub.add_parser("stop", help="stop a background server")
+    sub.add_parser("setup", help="add the Claude Code hooks chatdeck uses")
+    sub.add_parser("uninstall", help="remove the hooks and autostart")
+    s = sub.add_parser("autostart", help="start chatdeck at login: on, off or status")
+    s.add_argument("state", choices=["on", "off", "status"]); port_arg(s)
+    s.add_argument("--hotkey", default="", help='Windows: shortcut key for the Start menu entry, e.g. "Ctrl+Alt+A"')
+    d = sub.add_parser("demo", help="try chatdeck with made-up chats")
+    d.add_argument("--port", type=int, default=47199, help="default 47199"); d.add_argument("--no-open", action="store_true")
+    port_arg(sub.add_parser("bubble", help="Windows: start the corner button and tray icon"))
+    h = sub.add_parser("hook", help=argparse.SUPPRESS); h.add_argument("name", choices=["statusline", "waiting"])
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or (argv[0].startswith("-") and argv[0] not in ("-h", "--help", "--version")):
+        argv.insert(0, "open")   # plain `chatdeck` (with or without options) starts and opens the dashboard
+    a = p.parse_args(argv)
+    {"open": cmd_open, "serve": cmd_serve, "stop": cmd_stop, "setup": cmd_setup, "uninstall": cmd_uninstall,
+     "autostart": cmd_autostart, "demo": cmd_demo, "bubble": cmd_bubble, "hook": cmd_hook}[a.cmd](a)

chatdeck/config.py

@@ -0,0 +1,34 @@
+"""Where chatdeck keeps its data, and its settings (~/.chatdeck/config.json).
+Environment variables (CHATDECK_PORT, CHATDECK_TERMINAL, CHATDECK_VDLIB, CHATDECK_DIR) override the file."""
+import json, os
+
+HOME = os.path.expanduser("~")
+DATA = os.environ.get("CHATDECK_DIR") or os.path.join(HOME, ".chatdeck")
+FILE = os.path.join(DATA, "config.json")
+DEFAULT_PORT = 47123
+CLAUDE_SETTINGS = os.path.join(HOME, ".claude", "settings.json")
+DEMO = bool(os.environ.get("CHATDECK_DEMO"))   # `chatdeck demo`: made-up chats, nothing outside them is touched
+
+
+def load():
+    try:
+        with open(FILE) as f: return json.load(f)
+    except (OSError, ValueError):
+        return {}
+
+
+def save(cfg):
+    os.makedirs(DATA, exist_ok=True)
+    tmp = FILE + ".tmp"
+    with open(tmp, "w") as f: json.dump(cfg, f, indent=2)
+    os.replace(tmp, FILE)
+
+
+def get(key, default=None):
+    env = os.environ.get("CHATDECK_" + key.upper())
+    if env: return env
+    return load().get(key, default)
+
+
+def port():
+    return int(get("port") or DEFAULT_PORT)

chatdeck/demo.py

@@ -0,0 +1,141 @@
+"""Demo mode: a made-up home folder with Claude Code chats in a few projects, some of them
+"running", so chatdeck can be tried (and screenshotted) without real chats.
+
+`chatdeck demo` builds it in a temp folder and runs the server with HOME pointing there."""
+import datetime, json, os, random, time, uuid
+
+# (project folder, title, days ago, context tokens, cost, running status, turns)
+# A turn is (you, tool name, tool input, tool output, Claude's reply); tool parts may be None.
+CHATS = [
+    ("code/webshop", "Add Stripe checkout to the cart page", 0, 142_000, 3.84, "busy", [
+        ("Add Stripe checkout to the cart page. Use their hosted checkout, not Elements.",
+         "Read", {"file_path": "src/pages/cart.tsx"}, "export default function Cart() { ... }",
+         "The cart page renders line items from `useCart()`. I'll add a server route that creates a Checkout "
+         "Session and a **Pay** button that redirects to it."),
+        ("Sounds good. Keep the test keys in .env.local",
+         "Edit", {"file_path": "src/server/checkout.ts"}, "File updated",
+         "Added `POST /api/checkout`. It reads `STRIPE_SECRET_KEY` from `.env.local` and returns the session URL."),
+        ("Now handle the success and cancel pages",
+         "Bash", {"command": "npm test -- checkout"}, "PASS  tests/checkout.test.ts (4 tests)",
+         "Both pages are in, and the checkout tests pass. Running the webhook tests next."),
+    ]),
+    ("code/webshop/.claude/worktrees/dark-mode", "Dark mode for the storefront", 1, 64_000, 1.12, None, [
+        ("Add a dark mode that follows the system setting",
+         "Grep", {"pattern": "--color-bg"}, "src/styles/tokens.css:3",
+         "Colors are already tokens in `tokens.css`, so dark mode is one `prefers-color-scheme` block."),
+        ("Do it, and add a toggle in the footer", None, None, None,
+         "Done: the toggle stores the choice in localStorage and falls back to the system setting."),
+    ]),
+    ("code/webshop", "Fix flaky cart total test", 2, 38_000, 0.61, None, [
+        ("cart total test fails about 1 in 10 runs", "Bash", {"command": "npm test -- cart --repeat 20"},
+         "2 failed, 18 passed", "It rounds floats. Prices should be integer cents - switching the cart to cents."),
+    ]),
+    ("code/api-server", "Rate-limit the public API", 0, 96_000, 2.07, "waiting", [
+        ("Add rate limiting to the public API, 100 requests a minute per key",
+         "Read", {"file_path": "app/middleware.py"}, "def auth_middleware(request): ...",
+         "I'll add a token-bucket limiter after auth, backed by Redis so it works across workers."),
+        ("Yes, and return Retry-After", "Bash", {"command": "pip install redis"}, None,
+         "I need to install the `redis` package to continue."),
+    ]),
+    ("code/api-server", "Migrate users table to Postgres 16", 1, 210_000, 5.26, None, [
+        ("We're moving from Postgres 12 to 16. Plan the users table migration",
+         "Bash", {"command": "pg_dump --schema-only -t users"}, "CREATE TABLE users (...)",
+         "The table uses `md5` passwords and an old `citext` version. Plan: upgrade extensions, switch to "
+         "scram-sha-256, then run `pg_upgrade --link`."),
+        ("Write it up as a runbook", None, None, None, "Wrote `docs/runbooks/postgres-16.md` with rollback steps."),
+    ]),
+    ("code/api-server", "Why is /orders slow?", 4, 51_000, 0.94, None, [
+        ("GET /orders takes 3 seconds for big accounts", "Bash", {"command": "EXPLAIN ANALYZE SELECT ..."},
+         "Seq Scan on order_items  (cost=0.00..48211.00)", "It scans `order_items`. An index on `order_id` fixes it: 3s to 40ms."),
+    ]),
+    ("code/mobile-app", "Push notifications on Android", 0, 188_000, 4.41, "idle", [
+        ("Set up push notifications on Android with FCM", "Read", {"file_path": "android/app/build.gradle"}, "...",
+         "Added the Firebase plugin and a `NotificationService`. You'll need to drop `google-services.json` into `android/app`."),
+        ("Done, it's there. Test it", "Bash", {"command": "npx react-native run-android"}, "BUILD SUCCESSFUL",
+         "A test notification arrives on the emulator, both in the foreground and the background."),
+    ]),
+    ("code/mobile-app", "Upgrade to React Native 0.76", 5, 120_000, 2.88, None, [
+        ("Upgrade us to React Native 0.76", "Bash", {"command": "npx react-native upgrade 0.76"}, "Upgrade complete",
+         "Upgraded. Two libraries needed new versions; the app builds on iOS and Android."),
+    ]),
+    ("code/blog", "Write a post about SQLite in production", 3, 44_000, 0.73, None, [
+        ("Draft a blog post: why we run SQLite in production", None, None, None,
+         "Here's a draft with three parts: why it's enough, how we back it up (Litestream), and where it isn't enough."),
+    ]),
+    ("dotfiles", "Tidy up my zsh config", 6, 22_000, 0.31, None, [
+        ("My zsh takes 2 seconds to start", "Bash", {"command": "zsh -xv -i -c exit 2>&1 | tail"}, "nvm.sh ...",
+         "Most of it is `nvm`. Loading it lazily brings startup to 0.2 seconds."),
+    ]),
+    ("", "Plan my week", 0, 9_000, 0.08, None, [
+        ("Help me plan this week: ship checkout, the Postgres move, and the blog post", None, None, None,
+         "Checkout Monday to Tuesday, the Postgres runbook review Wednesday, the migration Thursday night, "
+         "and the blog post Friday."),
+    ]),
+]
+
+
+def _line(f, d): f.write(json.dumps(d) + "\n")
+
+
+def build(root):
+    """Write the demo home into root (an empty folder). Returns the CHATDECK_DIR to use."""
+    rnd = random.Random(7); now = time.time()
+    projects = os.path.join(root, ".claude", "projects"); data = os.path.join(root, ".chatdeck")
+    agents = []
+    for i, (folder, title, ago, ctx, cost, run, turns) in enumerate(CHATS):
+        run_name = {"Add Stripe checkout to the cart page": "stripe-checkout", "Rate-limit the public API": "api-rate-limit",
+                    "Push notifications on Android": "android-push"}.get(title)
+        cwd = os.path.join(root, folder) if folder else root
+        os.makedirs(cwd, exist_ok=True)
+        sid = str(uuid.UUID(int=rnd.getrandbits(128)))
+        pdir = os.path.join(projects, cwd.replace("/", "-").replace(".", "-")); os.makedirs(pdir, exist_ok=True)
+        path = os.path.join(pdir, sid + ".jsonl")
+        end = now - ago * 86400 - rnd.randint(5, 50) * 60 if not run else now - rnd.randint(1, 4) * 60
+        t = end - len(turns) * 600
+
+        def base(kind):
+            return {"type": kind, "timestamp": datetime.datetime.fromtimestamp(t, datetime.timezone.utc).isoformat()
+                    .replace("+00:00", "Z"), "cwd": cwd, "sessionId": sid, "uuid": str(uuid.uuid4())}
+        with open(path, "w") as f:
+            for n, (you, tool, inp, out, reply) in enumerate(turns):
+                _line(f, dict(base("user"), message={"role": "user", "content": you}))
+                last = n == len(turns) - 1
+                usage = {"input_tokens": rnd.randint(200, 2000), "output_tokens": rnd.randint(2000, 9000) * (1 + 6 * (ago > 0)),   # older chats stand for a whole day's work
+                         "cache_creation_input_tokens": rnd.randint(min(8000, ctx // 4), min(30000, ctx // 2))}
+                usage["cache_read_input_tokens"] = max(0, (ctx if last else ctx * (n + 1) // len(turns))
+                                                       - usage["input_tokens"] - usage["cache_creation_input_tokens"])
+                content = [{"type": "text", "text": reply}]
+                if tool: content.append({"type": "tool_use", "id": f"tu{i}{n}", "name": tool, "input": inp})
+                _line(f, dict(base("assistant"), message={"id": f"msg_{i}_{n}", "role": "assistant", "content": content, "usage": usage}))
+                if tool and out:
+                    t += 60
+                    _line(f, dict(base("user"), message={"role": "user", "content": [
+                        {"type": "tool_result", "tool_use_id": f"tu{i}{n}", "content": out}]}))
+                t += 540
+            _line(f, {"type": "ai-title", "aiTitle": title, "sessionId": sid})
+            _line(f, {"type": "cost-state", "totalCostUSD": cost, "sessionId": sid})
+        os.utime(path, (end, end))
+        if run:
+            agents.append({"pid": 0, "cwd": cwd, "kind": "interactive", "startedAt": int((end - 3600 * (i + 1)) * 1000),
+                           "sessionId": sid, "name": run_name,
+                           "status": "busy" if run == "busy" else "idle"})
+            if run == "waiting":
+                os.makedirs(os.path.join(data, "waiting"), exist_ok=True)
+                with open(os.path.join(data, "waiting", sid + ".json"), "w") as f:
+                    json.dump({"at": now, "message": "Claude needs your permission to use Bash"}, f)
+    # an empty chat, for the cleanup menu
+    empty = os.path.join(projects, os.listdir(projects)[0], str(uuid.UUID(int=rnd.getrandbits(128))) + ".jsonl")
+    open(empty, "w").close(); os.utime(empty, (now - 9 * 86400, now - 9 * 86400))
+
+    os.makedirs(os.path.join(data, "status"), exist_ok=True)
+    limits = {"five_hour": {"used_percentage": 62, "resets_at": int(now + 2 * 3600)},
+              "seven_day": {"used_percentage": 41, "resets_at": int(now + 3 * 86400)}}
+    with open(os.path.join(data, "status", agents[0]["sessionId"] + ".json"), "w") as f:
+        json.dump({"rate_limits": limits, "cost": {"total_cost_usd": 12.4}}, f)
+    with open(os.path.join(data, "limits-history.jsonl"), "w") as f:   # an hour of history, for the forecast
+        for k in range(7):
+            at = now - 3600 + k * 600
+            _line(f, {"t": at, "w": "five_hour", "p": 40 + k * 3, "r": limits["five_hour"]["resets_at"]})
+            _line(f, {"t": at, "w": "seven_day", "p": 39 + k * 0.3, "r": limits["seven_day"]["resets_at"]})
+    with open(os.path.join(data, "demo-agents.json"), "w") as f: json.dump(agents, f)
+    return data

chatdeck/desktop.py

@@ -0,0 +1,93 @@
+"""Opening the dashboard window, and the Windows side of things when running under WSL
+(the corner bubble, shortcuts in the Start menu and Startup folder)."""
+import filecmp, os, shutil, subprocess, webbrowser
+
+from . import terminals
+
+PKG = os.path.dirname(os.path.abspath(__file__))
+WIN_FILES = ("bubble.ps1", "start.ps1")
+
+
+# --- opening the dashboard ------------------------------------------------------------------
+
+def _app_browser():
+    """A Chromium browser that can open the dashboard as its own app window."""
+    k = terminals.kind()
+    if k == "wsl":
+        for p in ("/mnt/c/Program Files/Google/Chrome/Application/chrome.exe",
+                  "/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe",
+                  "/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe",
+                  "/mnt/c/Program Files/Microsoft/Edge/Application/msedge.exe"):
+            if os.path.exists(p): return [p]
+    elif k == "mac":
+        for app in ("Google Chrome", "Microsoft Edge", "Brave Browser", "Chromium"):
+            if os.path.isdir(f"/Applications/{app}.app"): return ["open", "-na", app, "--args"]
+    else:
+        for n in ("google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge", "brave-browser"):
+            if shutil.which(n): return [shutil.which(n)]
+    return None
+
+
+def open_dashboard(url):
+    b = _app_browser()
+    if b:
+        try:
+            subprocess.Popen([*b, f"--app={url}", "--window-size=520,900"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                             start_new_session=True, cwd="/mnt/c" if b[0].startswith("/mnt/") else None)
+            return
+        except OSError:
+            pass
+    webbrowser.open(url)
+
+
+# --- Windows (from WSL) ---------------------------------------------------------------------
+
+def _ps(script, timeout=30):
+    ps = terminals._win_exe("powershell.exe", "/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe")
+    r = subprocess.run([ps, "-NoProfile", "-Command", script], capture_output=True, text=True, cwd="/mnt/c", timeout=timeout)
+    return r.stdout.strip()
+
+
+def win_folders():
+    """{"local": ..., "startup": ..., "programs": ...} as Windows paths."""
+    out = _ps('[Environment]::GetFolderPath("LocalApplicationData"); [Environment]::GetFolderPath("Startup"); '
+              '[Environment]::GetFolderPath("Programs")')
+    local, startup, programs = out.splitlines()[:3]
+    return {"local": local, "startup": startup, "programs": programs}
+
+
+def to_wsl(win_path):
+    return subprocess.run(["wslpath", "-u", win_path], capture_output=True, text=True).stdout.strip()
+
+
+def install_windows_files(port, distro, cmd):
+    """Copy the bubble and launcher into %LOCALAPPDATA%\\chatdeck; returns that folder (Windows path)."""
+    folder = win_folders()["local"] + "\\chatdeck"
+    dest = to_wsl(folder); os.makedirs(dest, exist_ok=True)
+    shutil.copy(os.path.join(PKG, "windows", "bubble.ps1"), dest)
+    shutil.copy(os.path.join(PKG, "static", "logo.ico"), dest)
+    with open(os.path.join(PKG, "windows", "start.ps1")) as f: start = f.read()
+    start = (start.replace("__PORT__", str(port)).replace("__DISTRO__", distro).replace("__CMD__", cmd))
+    with open(os.path.join(dest, "start.ps1"), "w", newline="\r\n") as f: f.write(start)
+    return folder
+
+
+def shortcut(lnk, target_folder, args="", hotkey=""):
+    """Create a .lnk that runs start.ps1 (hidden) from target_folder."""
+    script = (f'$s = (New-Object -ComObject WScript.Shell).CreateShortcut("{lnk}"); '
+              f'$s.TargetPath = "$env:SystemRoot\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"; '
+              f'$s.Arguments = \'-NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File "{target_folder}\\start.ps1" {args}\'; '
+              f'$s.WindowStyle = 7; $s.IconLocation = "{target_folder}\\logo.ico"; $s.Description = "chatdeck"; '
+              + (f'$s.Hotkey = "{hotkey}"; ' if hotkey else "") + '$s.Save()')
+    _ps(script)
+
+
+def start_bubble(port):
+    """Start the corner bubble (and tray icon). A second start just shows the running one."""
+    folder = win_folders()["local"] + "\\chatdeck"
+    src, dst = os.path.join(PKG, "windows", "bubble.ps1"), os.path.join(to_wsl(folder), "bubble.ps1")
+    if not os.path.exists(dst) or not filecmp.cmp(src, dst, shallow=False):   # also after chatdeck is updated
+        os.makedirs(to_wsl(folder), exist_ok=True)
+        shutil.copy(src, dst)
+    _ps(f'Start-Process powershell.exe -WindowStyle Hidden -ArgumentList "-NoProfile","-WindowStyle","Hidden",'
+        f'"-ExecutionPolicy","Bypass","-File","{folder}\\bubble.ps1","-Port","{port}"')

chatdeck/hooks.py

@@ -0,0 +1,131 @@
+"""Claude Code hooks chatdeck relies on, and installing them into ~/.claude/settings.json.
+
+- Status line (`chatdeck hook statusline`): saves each session's status payload (plan limits,
+  cost) for the usage panel, then runs the status line the person already had, if any, so
+  their status line looks the same as before.
+- Notification (`chatdeck hook waiting`): marks a chat as waiting on a permission prompt or a
+  question. The dashboard treats the mark as cleared once the transcript moves on."""
+import json, os, re, shutil, subprocess, sys, time
+
+from . import config
+
+WAITING_MATCHER = "permission_prompt|elicitation_dialog"
+LEGACY = ("hooks/waiting.py",)   # hook commands from before chatdeck was a package
+
+
+def _write_atomic(path, data):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path + ".tmp", "w") as f: f.write(data)
+    os.replace(path + ".tmp", path)
+
+
+# --- running the hooks ----------------------------------------------------------------------
+
+def statusline(stdin=sys.stdin, stdout=sys.stdout):
+    raw = stdin.read()
+    try:
+        sid = json.loads(raw).get("session_id", "")
+        if re.fullmatch(r"[0-9a-f-]{36}", sid):
+            _write_atomic(os.path.join(config.DATA, "status", sid + ".json"), raw)
+    except (ValueError, AttributeError, OSError):
+        pass
+    wrapped = config.load().get("statusline_command")
+    if wrapped:
+        try:
+            r = subprocess.run(wrapped, shell=True, input=raw, capture_output=True, text=True, timeout=10)
+            stdout.write(r.stdout)
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+
+
+def waiting(stdin=sys.stdin):
+    try:
+        d = json.load(stdin)
+        sid = d.get("session_id", "")
+        if re.fullmatch(r"[0-9a-f-]{36}", sid):
+            _write_atomic(os.path.join(config.DATA, "waiting", sid + ".json"),
+                          json.dumps({"at": time.time(), "message": d.get("message", ""), "type": d.get("notification_type", "")}))
+    except (ValueError, AttributeError, OSError):
+        pass
+
+
+# --- installing them ------------------------------------------------------------------------
+
+def command():
+    """How settings.json should call chatdeck: the absolute path of the installed command,
+    or this Python running the package from wherever it lives."""
+    exe = shutil.which("chatdeck")
+    if exe: return exe
+    src = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    return f"PYTHONPATH={src} {sys.executable} -m chatdeck"
+
+
+def _ours(cmd):
+    return " hook statusline" in cmd or " hook waiting" in cmd or any(l in cmd for l in LEGACY)
+
+
+def _load(path):
+    try:
+        with open(path) as f: return json.load(f)
+    except FileNotFoundError:
+        return {}
+
+
+def _save(path, settings):
+    if os.path.exists(path):
+        backups = os.path.join(config.DATA, "backups"); os.makedirs(backups, exist_ok=True)
+        shutil.copy2(path, os.path.join(backups, "settings.json." + time.strftime("%Y%m%d-%H%M%S")))
+    _write_atomic(path, json.dumps(settings, indent=2) + "\n")
+
+
+def _drop_ours(settings):
+    """Remove chatdeck's Notification hooks (any version), leaving everything else as it was."""
+    groups = (settings.get("hooks") or {}).get("Notification") or []
+    for g in groups:
+        g["hooks"] = [h for h in g.get("hooks", []) if not _ours(h.get("command", ""))]
+    groups[:] = [g for g in groups if g.get("hooks")]
+    if "hooks" in settings and not groups:
+        settings["hooks"].pop("Notification", None)
+        if not settings["hooks"]: settings.pop("hooks")
+
+
+def install(path=config.CLAUDE_SETTINGS, cmd=None):
+    """Add chatdeck's hooks. Safe to run again. Returns a list of what changed."""
+    cmd = cmd or command(); settings = _load(path); cfg = config.load(); done = []
+    ours = f"{cmd} hook statusline"
+    sl = settings.get("statusLine") or {}
+    current = sl.get("command", "")
+    if current != ours:
+        if current and not _ours(current):
+            cfg["statusline_command"] = current
+            done.append(f"status line: kept yours ({current}) and saves usage before running it")
+        else:
+            done.append("status line: saves usage for the dashboard")
+        settings["statusLine"] = {**sl, "type": "command", "command": ours}
+    _drop_ours(settings)
+    groups = settings.setdefault("hooks", {}).setdefault("Notification", [])
+    hook = {"type": "command", "command": f"{cmd} hook waiting", "async": True}
+    group = next((g for g in groups if g.get("matcher") == WAITING_MATCHER), None)
+    if group: group.setdefault("hooks", []).append(hook)
+    else: groups.append({"matcher": WAITING_MATCHER, "hooks": [hook]})
+    done.append("notification hook: flags chats waiting for you")
+    _save(path, settings); config.save(cfg)
+    return done
+
+
+def uninstall(path=config.CLAUDE_SETTINGS):
+    """Take chatdeck's hooks out again and put back the status line that was there before."""
+    settings = _load(path); cfg = config.load(); done = []
+    sl = settings.get("statusLine") or {}
+    if _ours(sl.get("command", "")):
+        prev = cfg.pop("statusline_command", None)
+        if prev:
+            settings["statusLine"] = {**sl, "command": prev}; done.append(f"status line: back to {prev}")
+        else:
+            settings.pop("statusLine"); done.append("status line: removed")
+    before = json.dumps(settings.get("hooks"))
+    _drop_ours(settings)
+    if json.dumps(settings.get("hooks")) != before: done.append("notification hook: removed")
+    if done:
+        _save(path, settings); config.save(cfg)
+    return done