ctally 0.2.0__py3-none-any.whl

ctally/__init__.py

@@ -0,0 +1,3 @@
+"""CTally: a floating status light for your Claude Code sessions. Whose turn is it?"""
+
+__version__ = "0.2.0"

ctally/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

ctally/claude_hooks.py

@@ -0,0 +1,143 @@
+"""Add CTally's hooks to Claude Code's settings, or take them out again.
+
+The settings file (~/.claude/settings.json) is merged, never overwritten: other hooks and
+settings are left as they are, and a timestamped backup is written before any change.
+Earlier CTally hooks, and those from when it was called Claude Pet, are replaced rather
+than duplicated, so running it twice is harmless.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import tempfile
+import time
+from importlib import resources
+from pathlib import Path
+
+SETTINGS = Path.home() / ".claude" / "settings.json"
+SCRIPT = Path.home() / ".claude" / "hooks" / "ctally.sh"
+HOOK = '"$HOME/.claude/hooks/ctally.sh"'
+
+# Each event, and the state it reports. No "matcher": these events take none.
+EVENTS = {
+    "UserPromptSubmit": "working",  # a turn starts
+    "PreToolUse": "working",        # a tool is about to run
+    "PostToolUse": "working",       # back to work after a permission prompt
+    "Stop": "done",                 # the turn is over, unless agents still run behind it
+    "Notification": "waiting",      # a permission prompt, or idle waiting for input
+    "SessionEnd": "end",            # the session is gone
+    "SubagentStart": "agent-start", # a subagent, maybe one of a workflow's, sets off
+    "SubagentStop": "agent-stop",   # and comes back
+}
+
+# "claude-pet" catches the hooks from before the rename, inline or scripted.
+MARKERS = ("ctally", "claude-pet")
+
+
+class SettingsError(Exception):
+    """The settings file can't be read or isn't what we expect; it was left alone."""
+
+
+def is_ours(hook: dict) -> bool:
+    return any(marker in hook.get("command", "") for marker in MARKERS)
+
+
+def configure(settings: dict, install: bool) -> dict:
+    """Settings with every CTally hook removed, then (if installing) added back."""
+    settings = json.loads(json.dumps(settings))  # work on a copy
+    hooks = settings.get("hooks", {})
+    for event in list(hooks):
+        kept = []
+        for group in hooks[event]:
+            # Only our hooks go: others sharing a group with them (merged in by hand) stay.
+            theirs = [hook for hook in group.get("hooks", []) if not is_ours(hook)]
+            if len(theirs) == len(group.get("hooks", [])):
+                kept.append(group)
+            elif theirs:
+                kept.append({**group, "hooks": theirs})
+        if kept:
+            hooks[event] = kept
+        else:
+            del hooks[event]
+    if install:
+        for event, state in EVENTS.items():
+            hooks.setdefault(event, []).append(
+                {"hooks": [{"type": "command", "command": f"{HOOK} {state}"}]})
+    if hooks:
+        settings["hooks"] = hooks
+    else:
+        settings.pop("hooks", None)
+    return settings
+
+
+def update(install: bool, path: Path = SETTINGS) -> str:
+    """Installs or removes the hooks in a settings file; returns what happened."""
+    settings = {}
+    # Only a file that is really not there counts as empty. One that merely can't be seen (no
+    # permission, or a sandbox hiding it) would otherwise be replaced by just our hooks.
+    try:
+        text = path.read_text(encoding="utf-8")
+        exists = True
+    except FileNotFoundError:
+        exists = False
+    except OSError as error:
+        raise SettingsError(f"Can't read {path} ({error.strerror}); left it alone.") from error
+    if exists:
+        try:
+            settings = json.loads(text) if text.strip() else {}
+        except json.JSONDecodeError as error:
+            raise SettingsError(f"{path} is not valid JSON ({error}); left it alone.") from error
+        if not isinstance(settings, dict):
+            raise SettingsError(f"{path} does not hold a JSON object; left it alone.")
+
+    updated = configure(settings, install)
+    if updated == settings and exists:
+        return f"Claude Code hooks already {'installed' if install else 'removed'} in {path}"
+
+    notes = []
+    if exists:
+        notes.append(f"Backed up {path} to {backup(path)}")
+    # A symlink (into a dotfiles checkout, say) is written through, not replaced by a file.
+    target = Path(os.path.realpath(path))
+    target.parent.mkdir(parents=True, exist_ok=True)
+    # Write beside the file, then swap it in, so a crash can't leave half a settings file.
+    fd, temp = tempfile.mkstemp(dir=target.parent, prefix=".settings.", suffix=".json")
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        json.dump(updated, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+    if target.exists():
+        shutil.copymode(target, temp)
+    os.replace(temp, target)
+    notes.append(f"Claude Code hooks {'installed in' if install else 'removed from'} {path}")
+    return "\n".join(notes)
+
+
+def backup(path: Path) -> Path:
+    """Copies a file aside, never over an earlier backup, even one made the same second."""
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    copy, n = Path(f"{path}.bak.{stamp}"), 1
+    while copy.exists():
+        n += 1
+        copy = Path(f"{path}.bak.{stamp}-{n}")
+    shutil.copy2(path, copy)
+    return copy
+
+
+def install_script() -> None:
+    """Puts the hook script where the hooks call it."""
+    SCRIPT.parent.mkdir(parents=True, exist_ok=True)
+    source = resources.files("ctally").joinpath("hooks/ctally.sh").read_bytes()
+    temp = SCRIPT.with_name(".ctally.sh.new")
+    temp.write_bytes(source)
+    temp.chmod(0o755)
+    os.replace(temp, SCRIPT)
+
+
+def remove_scripts() -> None:
+    for name in ("ctally.sh", "claude-pet.sh"):
+        (SCRIPT.parent / name).unlink(missing_ok=True)
+    try:
+        SCRIPT.parent.rmdir()               # only if nothing else lives there
+    except OSError:
+        pass

ctally/cli.py

@@ -0,0 +1,180 @@
+"""ctally: CTally from the shell and from tmux.
+
+  ctally run                    start the indicator (setup arranges this at login)
+  ctally setup [--tmux]         install the Claude Code hooks, start CTally at login, and start it
+                                now; --tmux also binds prefix + J and puts the counts in tmux's
+                                status line
+  ctally uninstall              undo all of that (then: pipx uninstall ctally)
+
+  ctally status [--tmux]        counts of live sessions by state, most urgent first: "!1 ▶2 ✓5 ·1"
+                                (waiting, working, done, idle); --tmux adds status-line colours
+  ctally list                   one line per live session: state, tmux pane, subagents running,
+                                project, id
+  ctally jump [pane client socket]
+                                switch a tmux client to the session that needs you: waiting first,
+                                then finished, longest-waiting first. Run it again to move on to
+                                the next one. A key binding passes '#{pane_id}' '#{client_name}'
+                                '#{socket_path}'.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import NamedTuple
+
+from . import __version__, system
+from .sessions import STATE_DIR
+
+GLYPH = {"waiting": "!", "working": "▶", "done": "✓", "idle": "·"}
+COLOUR = {"waiting": "#ffb329", "working": "#4accf2", "done": "#45e087", "idle": "#99a6bd"}
+RANK = {"waiting": 0, "done": 1, "working": 2, "idle": 3}
+
+
+class Live(NamedTuple):
+    rank: int
+    modified: float
+    state: str
+    pid: int
+    id: str
+    project: str
+
+
+def live_sessions() -> list[Live]:
+    """Each live session, most urgent first and, within a state, longest-waiting first.
+    Sessions whose claude process is gone are skipped."""
+    found = []
+    try:
+        names = [n for n in os.listdir(STATE_DIR) if not n.startswith(".")]
+    except OSError:
+        names = []
+    for name in names:
+        path = STATE_DIR / name
+        try:
+            fields = path.read_text(errors="replace").split()
+            modified = path.stat().st_mtime
+        except OSError:
+            continue
+        if len(fields) < 2 or not fields[1].isdigit():
+            continue
+        pid = int(fields[1])
+        if not system.is_alive(pid):
+            continue
+        state = fields[0] if fields[0] in RANK else "idle"
+        found.append(Live(RANK[state], modified, state, pid, name, " ".join(fields[2:]) or "?"))
+    return sorted(found)
+
+
+def agents_running(sid: str) -> int:
+    try:
+        return sum(1 for n in os.listdir(STATE_DIR / ".agents" / sid) if not n.startswith("."))
+    except OSError:
+        return 0
+
+
+def status(tmux: bool) -> None:
+    counts: dict[str, int] = {}
+    for session in live_sessions():
+        counts[session.state] = counts.get(session.state, 0) + 1
+    items = []
+    for state in ("waiting", "working", "done", "idle"):
+        if counts.get(state):
+            item = f"{GLYPH[state]}{counts[state]}"
+            items.append(f"#[fg={COLOUR[state]}]{item}" if tmux else item)
+    out = " ".join(items)
+    print(out + "#[default]" if tmux and out else out)
+
+
+def list_sessions() -> None:
+    for session in live_sessions():
+        target = system.tmux_pane(session.pid)
+        location = (system.tmux_location(target) if target else None) or "-"
+        n = agents_running(session.id)
+        agents = "-" if n == 0 else "1 agent" if n == 1 else f"{n} agents"
+        print(f"{session.state:<8} {location:<16} {agents:<9} {session.project:<24} {session.id}")
+
+
+def jump(current: str | None, client: str | None, here: str | None) -> int:
+    current = current or os.environ.get("TMUX_PANE", "")
+    here = here or os.environ.get("TMUX", "").split(",", 1)[0]
+    binary = system.tmux_binary() or "tmux"
+
+    def say(message: str) -> None:
+        if client and here:
+            system.run([binary, "-S", here, "display-message", "-c", client, message])
+        else:
+            print(message)
+
+    # Sessions that need me, in tmux, in order.
+    queue = []
+    for session in live_sessions():
+        if session.rank > 1:
+            continue
+        target = system.tmux_pane(session.pid)
+        if target:
+            queue.append((target, session))
+    if not queue:
+        say("CTally: nothing needs you")
+        return 0
+
+    # The one after the pane I'm on, so pressing again moves along the queue.
+    at = next((i for i, (target, _) in enumerate(queue) if target.pane == current), None)
+    target, session = queue[at + 1] if at is not None and at + 1 < len(queue) else queue[0]
+
+    if not here:
+        print(f"ctally jump: run it inside tmux (or bind it to a key); next up is "
+              f"{session.project} ({session.state})", file=sys.stderr)
+        return 1
+    if target.socket != here:
+        say(f"CTally: {session.project} is on another tmux server")
+        return 1
+    switch = [binary, "-S", target.socket, "switch-client"] + (["-c", client] if client else []) + ["-t", target.pane]
+    if system.run(switch) is None:
+        say(f"CTally: couldn't switch to {session.project}")
+        return 1
+    say(f"CTally: {session.project} · {session.state}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="ctally", description=__doc__.split("\n")[0],
+                                     formatter_class=argparse.RawDescriptionHelpFormatter,
+                                     epilog="\n".join(__doc__.split("\n")[2:]))
+    parser.add_argument("--version", action="version", version=f"ctally {__version__}")
+    commands = parser.add_subparsers(dest="command", metavar="command")
+    commands.add_parser("run", help="start the indicator")
+    setup = commands.add_parser("setup", help="install hooks, start at login, start now")
+    setup.add_argument("--tmux", action="store_true", help="also bind prefix + J and add tmux status-line counts")
+    setup.add_argument("--no-hooks", action="store_true", help="leave ~/.claude/settings.json alone")
+    setup.add_argument("--no-autostart", action="store_true", help="don't start CTally at login")
+    setup.add_argument("--no-launch", action="store_true", help="don't start CTally now")
+    commands.add_parser("uninstall", help="remove hooks, tmux setup, autostart and state")
+    status_ = commands.add_parser("status", help="counts by state")
+    status_.add_argument("--tmux", action="store_true", help="with tmux status-line colours")
+    commands.add_parser("list", help="one line per live session")
+    jump_ = commands.add_parser("jump", help="switch tmux to the session that needs you")
+    jump_.add_argument("pane", nargs="?")
+    jump_.add_argument("client", nargs="?")
+    jump_.add_argument("socket", nargs="?")
+    args = parser.parse_args(argv)
+
+    if args.command == "run":
+        from .gui.app import run          # Qt loads only for the indicator
+        return run()
+    if args.command == "setup":
+        from . import install
+        return install.setup(tmux=args.tmux, hooks=not args.no_hooks,
+                             autostart=not args.no_autostart, launch=not args.no_launch)
+    if args.command == "uninstall":
+        from . import install
+        return install.uninstall()
+    if args.command == "status":
+        status(args.tmux)
+        return 0
+    if args.command == "list":
+        list_sessions()
+        return 0
+    if args.command == "jump":
+        return jump(args.pane, args.client, args.socket)
+    parser.print_help()
+    return 2

ctally/focus.py

@@ -0,0 +1,144 @@
+"""Brings a session's terminal to the front.
+
+Inside tmux, that means switching tmux to the session's pane, then raising the terminal
+attached to that tmux session (or opening one if none is). Outside tmux, it means raising the
+terminal the session runs in: on macOS the exact Terminal tab, or the app for anything else
+(iTerm2, VS Code, the Claude desktop app); on Linux the terminal's window, where the desktop
+allows it (X11, with xdotool installed; Wayland lets no app raise another's window).
+
+All of this shells out, so it runs off the main thread, and it stays silent when anything
+along the way is missing.
+"""
+from __future__ import annotations
+
+import shlex
+import shutil
+import subprocess
+import threading
+
+from . import system
+
+TERMINAL = "com.apple.Terminal"
+
+# Picks the Terminal tab whose tty matches, and puts its window in front.
+RAISE_TAB = """
+on run argv
+  set target to item 1 of argv
+  tell application "Terminal"
+    repeat with w in windows
+      repeat with t in tabs of w
+        if tty of t is target then
+          set miniaturized of w to false
+          set selected tab of w to t
+          set index of w to 1
+          activate
+          return
+        end if
+      end repeat
+    end repeat
+  end tell
+end run
+"""
+
+
+def focus(pid: int) -> None:
+    if pid > 0:
+        threading.Thread(target=_focus_now, args=(pid,), daemon=True).start()
+
+
+def _focus_now(pid: int) -> None:
+    target = system.tmux_pane(pid)
+    if target:
+        _focus_tmux(target)
+    else:
+        _raise(system.tty(pid), pid)
+
+
+def _focus_tmux(target: system.TmuxPane) -> None:
+    def tmux(*args: str) -> str | None:
+        return system.run([target.binary, "-S", target.socket, *args])
+
+    tmux("select-window", "-t", target.pane)
+    tmux("select-pane", "-t", target.pane)
+    session = (tmux("display-message", "-p", "-t", target.pane, "#{session_name}") or "").strip()
+    if not session:
+        return
+
+    # The terminal attached to that tmux session that I used most recently.
+    clients = []
+    for line in (tmux("list-clients", "-t", "=" + session,
+                      "-F", "#{client_activity} #{client_pid} #{client_tty}") or "").splitlines():
+        fields = line.split(" ", 2)
+        if len(fields) == 3 and fields[0].isdigit() and fields[1].isdigit():
+            clients.append((int(fields[0]), int(fields[1]), fields[2]))
+    if clients:
+        _, client_pid, client_tty = max(clients)
+        _raise(client_tty, client_pid)
+        return
+
+    # Nobody is looking at that session: open a terminal onto it.
+    attach = shlex.join([target.binary, "-S", target.socket, "attach-session", "-t", "=" + session])
+    if system.MAC:
+        quoted = attach.replace("\\", "\\\\").replace('"', '\\"')
+        system.run(["osascript", "-e", 'tell application "Terminal"', "-e", f'do script "{quoted}"',
+                    "-e", "activate", "-e", "end tell"])
+    elif shutil.which("x-terminal-emulator"):
+        subprocess.Popen(["x-terminal-emulator", "-e", "sh", "-c", attach], start_new_session=True,
+                         stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+
+def _raise(tty: str | None, pid: int) -> None:
+    if system.MAC:
+        _raise_mac(tty, pid)
+    elif system.LINUX:
+        _raise_x11(pid)
+
+
+def _raise_mac(tty: str | None, pid: int) -> None:
+    app = _host_app(pid)
+    if app is None:
+        return
+    if tty and app.bundleIdentifier() == TERMINAL:
+        system.run(["osascript", "-e", RAISE_TAB, tty])
+        return
+    # The way the Dock does it: since macOS 14 an app can't push itself past the active one,
+    # and CTally is never active, so asking the app directly may be ignored.
+    from AppKit import NSWorkspace, NSWorkspaceOpenConfiguration
+    url = app.bundleURL()
+    if url is None:
+        app.activateWithOptions_(0)
+        return
+    configuration = NSWorkspaceOpenConfiguration.configuration()
+    configuration.setActivates_(True)
+    NSWorkspace.sharedWorkspace().openApplicationAtURL_configuration_completionHandler_(url, configuration, None)
+
+
+def _host_app(pid: int):
+    """The nearest ancestor that is an ordinary app: Terminal, for a shell in one of its tabs."""
+    from AppKit import NSApplicationActivationPolicyRegular, NSRunningApplication
+    current = pid
+    for _ in range(32):
+        app = NSRunningApplication.runningApplicationWithProcessIdentifier_(current)
+        if app is not None and app.activationPolicy() == NSApplicationActivationPolicyRegular:
+            return app
+        up = system.parent(current)
+        if not up or up <= 1 or up == current:
+            return None
+        current = up
+    return None
+
+
+def _raise_x11(pid: int) -> None:
+    """Activates the window of the nearest ancestor that has one: the terminal emulator."""
+    if not shutil.which("xdotool"):
+        return
+    current = pid
+    for _ in range(32):
+        windows = (system.run(["xdotool", "search", "--pid", str(current)]) or "").split()
+        if windows:
+            system.run(["xdotool", "windowactivate", windows[-1]])
+            return
+        up = system.parent(current)
+        if not up or up <= 1 or up == current:
+            return
+        current = up