chatdeck 0.1.0__tar.gz

chatdeck-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdifatah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chatdeck-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: chatdeck
+Version: 0.1.0
+Summary: A local dashboard for your Claude Code chats: what's running, what needs you, and what it costs.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Abdifatah09/chatdeck
+Project-URL: Issues, https://github.com/Abdifatah09/chatdeck/issues
+Keywords: claude,claude-code,dashboard,ai,cli
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# chatdeck
+
+A local dashboard for your Claude Code chats: see which chats are running and which need you,
+read and search old chats, track usage against your plan limits, and clean up transcripts.
+Python 3.9+ standard library only, no dependencies.
+
+![A tour of chatdeck: a chat waiting for permission, chats grouped by project, searching and reading an old chat, and the light theme](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/media/tour.gif)
+
+## Features
+
+- **Running now** – every live session with its context size and cost. Sessions stuck on a
+  permission prompt or a question get an amber **Waiting for you** badge and an optional chime.
+  **Open** jumps to the chat's terminal tab, **Rename** runs `/rename` in it so Claude names it after what it's about (double-click the name to type your own), and big chats get a
+  **Compact** button that runs `/compact`.
+- **Saved chats** – read any chat without resuming it, search across all messages,
+  rename (so you know what's in it), export to Markdown, resume in a terminal, delete.
+- **Usage** – tokens today and this week, top projects, 24h cost, and your 5-hour and weekly
+  limits with a forecast of when you'd hit them at the current pace.
+- **Cleanup** – delete empty chats or chats older than 7, 30 or 90 days. Shows disk usage.
+  Running chats are never deleted.
+- **By project** view: one section per project (git repo, including its worktrees and subfolders)
+  with its running and saved chats, and a **New chat** button that starts Claude Code in that project. Sort by recent, size, cost or messages. Light and dark themes.
+  Keyboard shortcuts: `/` search, `j`/`k` move, `Enter` read, `r` resume, `e` rename, `x` select, `Del` delete, `?` help.
+- **Windows corner button and tray icon** – pop the dashboard up from the corner of the screen.
+
+## Install
+
+```sh
+pipx install chatdeck          # once it's on PyPI; until then:
+pipx install git+https://github.com/Abdifatah09/chatdeck
+```
+
+No pip? Clone the repo and run `./install.sh`. It puts a `chatdeck` command in `~/.local/bin`
+that runs straight from the clone.
+
+## Try it first
+
+```sh
+chatdeck demo
+```
+
+opens chatdeck on a set of made-up chats (in a temporary folder, deleted when you stop it with Ctrl+C),
+so you can click around without touching your own. The screenshots here are from the demo.
+
+## Use
+
+```sh
+chatdeck                  # start the dashboard and open it
+chatdeck setup            # add the Claude Code hooks for plan limits and "waiting for you"
+chatdeck autostart on     # start it at login (Windows via WSL, macOS, Linux)
+chatdeck bubble           # Windows: the corner button and tray icon
+chatdeck demo             # try it with made-up chats
+chatdeck stop             # stop the background server
+chatdeck uninstall        # take the hooks and autostart out again
+```
+
+`chatdeck setup` keeps your existing status line: it saves the usage data first, then runs
+yours, so your status line looks the same. `chatdeck uninstall` puts it back, and your previous
+settings are backed up in `~/.chatdeck/backups`.
+
+## Privacy and security
+
+- Everything stays on your machine. chatdeck reads the transcripts Claude Code already writes to
+  `~/.claude/projects` and sends nothing anywhere: no accounts, no telemetry, no network calls
+  except to itself.
+- The server binds to 127.0.0.1 only. Every API call needs a token that changes each run, sent in a
+  custom header, so other websites open in your browser can't call it.
+- It only changes things you ask it to: deleting a chat removes its transcript (running chats are
+  never deleted), renaming adds a title line to it, and Rename and Compact on a running chat type
+  `/rename` or `/compact` into that chat's terminal, only while it's idle.
+- `chatdeck setup` edits `~/.claude/settings.json` and backs it up first; `chatdeck uninstall` undoes it.
+
+## See it in action
+
+| Find any chat by what was said in it | Every project in one place |
+|---|---|
+| ![searching for "upgrade" and opening the matching chat](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/media/search.gif) | ![switching to the by-project view, folding a project and the New chat button](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/media/projects.gif) |
+
+| Keyboard only: `j`/`k`, `Enter`, `e` to rename, `?` for help | Running chats, at a glance |
+|---|---|
+| ![moving through saved chats, reading one and renaming it from the keyboard](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/media/keyboard.gif) | ![three running chats: one waiting for permission, one working, one getting big](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/media/running.png) |
+
+## Screenshots
+
+![chatdeck showing three running chats, one waiting for permission, plan limits and a week of usage](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/dashboard.png)
+
+| By project | Reading a chat |
+|---|---|
+| ![chats grouped by project](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/by-project.png) | ![a saved chat open in the viewer](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/viewer.png) |
+
+| Light theme | The Windows pop-up |
+|---|---|
+| ![the light theme](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/light.png) | ![the pop-up from the corner button](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/popup.png) |
+
+## Windows corner button and tray icon
+
+A small always-on-top button sits in the bottom-left corner of the screen. Click it and the
+dashboard pops up above it; click again, or anywhere else, and it tucks away. The badge counts
+running chats and turns amber, with a pulsing ring, when one is waiting for you. Drag it to move
+it; right-click to hide it or for more. The same badge sits in the notification area by the
+clock, where a click pops the dashboard up in the bottom-right corner. It needs Chrome or Edge.
+Start it with `chatdeck bubble`, or let `chatdeck autostart on` start it at login.
+
+## Terminals
+
+**Resume**, **Open** and **Agents view** open or find a terminal for you:
+
+| Platform | Opens chats in | Open on a running chat |
+|---|---|---|
+| WSL | Windows Terminal (a new window each time) | finds its tab on any virtual desktop and switches to it |
+| macOS | Terminal, or iTerm2 if you run the dashboard from it | finds its tab by tty |
+| Linux | gnome-terminal, konsole, kitty, alacritty, wezterm, xfce4-terminal, tilix, foot or xterm | finds its window with `wmctrl` or `xdotool` (X11) |
+
+When no terminal can be opened, the dashboard copies the command to paste instead.
+Finding a running chat works by briefly giving its tab a unique title, so it doesn't work for
+tabs whose title is locked (Windows Terminal's `suppressApplicationTitle`).
+
+## Settings
+
+Settings live in `~/.chatdeck/config.json`, and environment variables override them:
+
+- `port` / `CHATDECK_PORT`: default 47123
+- `terminal` / `CHATDECK_TERMINAL`: which terminal to use, e.g. `kitty` or `iterm`
+- `tabs` / `CHATDECK_TABS` (WSL): `true` opens chats as tabs in your last Windows Terminal window instead of a new window each
+- `vdlib` / `CHATDECK_VDLIB` (WSL): Windows path to [VirtualDesktopLib.cs](https://github.com/MScholtes/VirtualDesktop),
+  which makes switching to a chat on another virtual desktop reliable
+- `CHATDECK_DIR`: where chatdeck keeps its data, default `~/.chatdeck`
+
+## Tests
+
+```sh
+python3 -m unittest discover -s tests
+```
+
+## Screenshots and videos
+
+Everything in `docs/` is recorded from `chatdeck demo` by a script, so it can be redone after UI changes
+(needs Node; uses Segoe UI from `/mnt/c/Windows/Fonts` when run under WSL):
+
+```sh
+cd scripts/promo && npm install && npx playwright-core install chromium-headless-shell
+npm run record                    # or just some: npm run record -- shots tour search projects keyboard
+```
+
+It writes the README screenshots to `docs/` and the GIFs, MP4s, framed screenshots and a 1280×640
+social preview card to `docs/media/`.

chatdeck-0.1.0/README.md

@@ -0,0 +1,146 @@
+# chatdeck
+
+A local dashboard for your Claude Code chats: see which chats are running and which need you,
+read and search old chats, track usage against your plan limits, and clean up transcripts.
+Python 3.9+ standard library only, no dependencies.
+
+![A tour of chatdeck: a chat waiting for permission, chats grouped by project, searching and reading an old chat, and the light theme](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/media/tour.gif)
+
+## Features
+
+- **Running now** – every live session with its context size and cost. Sessions stuck on a
+  permission prompt or a question get an amber **Waiting for you** badge and an optional chime.
+  **Open** jumps to the chat's terminal tab, **Rename** runs `/rename` in it so Claude names it after what it's about (double-click the name to type your own), and big chats get a
+  **Compact** button that runs `/compact`.
+- **Saved chats** – read any chat without resuming it, search across all messages,
+  rename (so you know what's in it), export to Markdown, resume in a terminal, delete.
+- **Usage** – tokens today and this week, top projects, 24h cost, and your 5-hour and weekly
+  limits with a forecast of when you'd hit them at the current pace.
+- **Cleanup** – delete empty chats or chats older than 7, 30 or 90 days. Shows disk usage.
+  Running chats are never deleted.
+- **By project** view: one section per project (git repo, including its worktrees and subfolders)
+  with its running and saved chats, and a **New chat** button that starts Claude Code in that project. Sort by recent, size, cost or messages. Light and dark themes.
+  Keyboard shortcuts: `/` search, `j`/`k` move, `Enter` read, `r` resume, `e` rename, `x` select, `Del` delete, `?` help.
+- **Windows corner button and tray icon** – pop the dashboard up from the corner of the screen.
+
+## Install
+
+```sh
+pipx install chatdeck          # once it's on PyPI; until then:
+pipx install git+https://github.com/Abdifatah09/chatdeck
+```
+
+No pip? Clone the repo and run `./install.sh`. It puts a `chatdeck` command in `~/.local/bin`
+that runs straight from the clone.
+
+## Try it first
+
+```sh
+chatdeck demo
+```
+
+opens chatdeck on a set of made-up chats (in a temporary folder, deleted when you stop it with Ctrl+C),
+so you can click around without touching your own. The screenshots here are from the demo.
+
+## Use
+
+```sh
+chatdeck                  # start the dashboard and open it
+chatdeck setup            # add the Claude Code hooks for plan limits and "waiting for you"
+chatdeck autostart on     # start it at login (Windows via WSL, macOS, Linux)
+chatdeck bubble           # Windows: the corner button and tray icon
+chatdeck demo             # try it with made-up chats
+chatdeck stop             # stop the background server
+chatdeck uninstall        # take the hooks and autostart out again
+```
+
+`chatdeck setup` keeps your existing status line: it saves the usage data first, then runs
+yours, so your status line looks the same. `chatdeck uninstall` puts it back, and your previous
+settings are backed up in `~/.chatdeck/backups`.
+
+## Privacy and security
+
+- Everything stays on your machine. chatdeck reads the transcripts Claude Code already writes to
+  `~/.claude/projects` and sends nothing anywhere: no accounts, no telemetry, no network calls
+  except to itself.
+- The server binds to 127.0.0.1 only. Every API call needs a token that changes each run, sent in a
+  custom header, so other websites open in your browser can't call it.
+- It only changes things you ask it to: deleting a chat removes its transcript (running chats are
+  never deleted), renaming adds a title line to it, and Rename and Compact on a running chat type
+  `/rename` or `/compact` into that chat's terminal, only while it's idle.
+- `chatdeck setup` edits `~/.claude/settings.json` and backs it up first; `chatdeck uninstall` undoes it.
+
+## See it in action
+
+| Find any chat by what was said in it | Every project in one place |
+|---|---|
+| ![searching for "upgrade" and opening the matching chat](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/media/search.gif) | ![switching to the by-project view, folding a project and the New chat button](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/media/projects.gif) |
+
+| Keyboard only: `j`/`k`, `Enter`, `e` to rename, `?` for help | Running chats, at a glance |
+|---|---|
+| ![moving through saved chats, reading one and renaming it from the keyboard](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/media/keyboard.gif) | ![three running chats: one waiting for permission, one working, one getting big](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/media/running.png) |
+
+## Screenshots
+
+![chatdeck showing three running chats, one waiting for permission, plan limits and a week of usage](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/dashboard.png)
+
+| By project | Reading a chat |
+|---|---|
+| ![chats grouped by project](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/by-project.png) | ![a saved chat open in the viewer](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/viewer.png) |
+
+| Light theme | The Windows pop-up |
+|---|---|
+| ![the light theme](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/light.png) | ![the pop-up from the corner button](https://raw.githubusercontent.com/Abdifatah09/chatdeck/main/docs/popup.png) |
+
+## Windows corner button and tray icon
+
+A small always-on-top button sits in the bottom-left corner of the screen. Click it and the
+dashboard pops up above it; click again, or anywhere else, and it tucks away. The badge counts
+running chats and turns amber, with a pulsing ring, when one is waiting for you. Drag it to move
+it; right-click to hide it or for more. The same badge sits in the notification area by the
+clock, where a click pops the dashboard up in the bottom-right corner. It needs Chrome or Edge.
+Start it with `chatdeck bubble`, or let `chatdeck autostart on` start it at login.
+
+## Terminals
+
+**Resume**, **Open** and **Agents view** open or find a terminal for you:
+
+| Platform | Opens chats in | Open on a running chat |
+|---|---|---|
+| WSL | Windows Terminal (a new window each time) | finds its tab on any virtual desktop and switches to it |
+| macOS | Terminal, or iTerm2 if you run the dashboard from it | finds its tab by tty |
+| Linux | gnome-terminal, konsole, kitty, alacritty, wezterm, xfce4-terminal, tilix, foot or xterm | finds its window with `wmctrl` or `xdotool` (X11) |
+
+When no terminal can be opened, the dashboard copies the command to paste instead.
+Finding a running chat works by briefly giving its tab a unique title, so it doesn't work for
+tabs whose title is locked (Windows Terminal's `suppressApplicationTitle`).
+
+## Settings
+
+Settings live in `~/.chatdeck/config.json`, and environment variables override them:
+
+- `port` / `CHATDECK_PORT`: default 47123
+- `terminal` / `CHATDECK_TERMINAL`: which terminal to use, e.g. `kitty` or `iterm`
+- `tabs` / `CHATDECK_TABS` (WSL): `true` opens chats as tabs in your last Windows Terminal window instead of a new window each
+- `vdlib` / `CHATDECK_VDLIB` (WSL): Windows path to [VirtualDesktopLib.cs](https://github.com/MScholtes/VirtualDesktop),
+  which makes switching to a chat on another virtual desktop reliable
+- `CHATDECK_DIR`: where chatdeck keeps its data, default `~/.chatdeck`
+
+## Tests
+
+```sh
+python3 -m unittest discover -s tests
+```
+
+## Screenshots and videos
+
+Everything in `docs/` is recorded from `chatdeck demo` by a script, so it can be redone after UI changes
+(needs Node; uses Segoe UI from `/mnt/c/Windows/Fonts` when run under WSL):
+
+```sh
+cd scripts/promo && npm install && npx playwright-core install chromium-headless-shell
+npm run record                    # or just some: npm run record -- shots tour search projects keyboard
+```
+
+It writes the README screenshots to `docs/` and the GIFs, MP4s, framed screenshots and a 1280×640
+social preview card to `docs/media/`.

chatdeck-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]   # for license = "MIT" and license-files
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chatdeck"
+dynamic = ["version"]
+description = "A local dashboard for your Claude Code chats: what's running, what needs you, and what it costs."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["claude", "claude-code", "dashboard", "ai", "cli"]
+classifiers = [
+  "Environment :: Console",
+  "Environment :: Web Environment",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://github.com/Abdifatah09/chatdeck"
+Issues = "https://github.com/Abdifatah09/chatdeck/issues"
+
+[project.scripts]
+chatdeck = "chatdeck.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "chatdeck.__version__" }
+
+[tool.setuptools.package-data]
+chatdeck = ["static/*", "windows/*"]

chatdeck-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chatdeck-0.1.0/src/chatdeck/__init__.py

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

chatdeck-0.1.0/src/chatdeck/__main__.py

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

chatdeck-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)