hatcheck 0.1.0__py3-none-any.whl

hatcheck/__init__.py

@@ -0,0 +1,6 @@
+"""Hatcheck: Claude Code and Codex accounts on one computer, each kept apart.
+
+The subcommands are the scripts in this folder; hatcheck.py beside it, or the hatcheck
+command a package install makes, runs them. They load each other by path, so keep the
+folder whole."""
+__version__ = "0.1.0"

hatcheck/best.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""Which account to use now, and where to carry a session.
+
+Usage:
+    hatcheck best [--for SESSION] [--cached]
+
+  --for    : where to carry a session, by its ID or the start of it: the hatcheck
+             move command for the best other account of its agent.
+  --cached : don't call the APIs; use the snapshots Claude Code and Codex last saved.
+
+Claude Code accounts are ranked as hatcheck usage sorts them. First come those with
+Fable left, the soonest Fable reset on top, since what's left goes unused once it
+resets. Next come those out of Fable, or out of the weekly limit for all models
+that it counts against too, the soonest back on top. Then come accounts without a
+Fable limit, by the tightest limit that applies (the one with the least left of the
+5-hour and weekly limits), the sooner reset first on a tie. Codex homes are ranked
+by their tightest limit too. Each line ends with the command that starts the agent
+on that account. --for skips accounts that are out, and the session's own.
+
+Advice only: it runs when you ask, prints commands, and never starts, moves or
+switches anything. Using several accounts to get around one plan's limits may break
+Anthropic's or OpenAI's terms; this is for choosing between accounts you may use for
+the work at hand, such as your own and your company's.
+
+This script loads sessions.py, usage.py and move.py, so keep them in one folder.
+"""
+import argparse
+import importlib.util
+import os
+import sys
+import time
+
+
+def load_sibling(name, file):
+    sys.dont_write_bytecode = True  # leave no __pycache__ folder beside the scripts
+    path = os.path.join(os.path.dirname(os.path.realpath(__file__)), file)
+    spec = importlib.util.spec_from_file_location(name, path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def meters(usage, saved_at, now, u):
+    """(short name, % left, next reset, kind) for an account's 5-hour, weekly and per-model limits."""
+    out = []
+    for r in (usage or {}).get("limits") or []:
+        if isinstance(r, dict):
+            left, reset = u.meter_state(r, saved_at, now)
+            out.append((u.row_label(r, short=True), left, reset, r.get("kind")))
+    return out
+
+
+def rank(usage, saved_at, now, u):
+    """Sort key and state for an account: (group, time or -% left, reset), and whether it
+    has room now. Groups: 0 Fable left, 1 out of Fable, 2 no Fable limit, 3 no data."""
+    if usage is None:
+        return (3, 0, 0), False
+    group, at = u.fable_rank(usage, saved_at, now)
+    if group < 2:
+        return (group, at, 0), group == 0
+    rows = [m for m in meters(usage, saved_at, now, u) if not str(m[3] or "").endswith("_scoped")]
+    if not rows:
+        return (2, 0, 0), True
+    tightest = min(rows, key=lambda m: (m[1], m[2] or float("inf")))
+    return (2, -tightest[1], tightest[2] or float("inf")), tightest[1] > 0
+
+
+def summary(usage, saved_at, why, now, u, room):
+    """What the line says about an account: its Fable limit first, then the tightest other."""
+    if usage is None:
+        return "no data (%s)" % why
+    rows = meters(usage, saved_at, now, u)
+    fable = next(((n, left, reset) for n, left, reset, kind in rows if kind == "weekly_scoped" and "fable" in n.lower()),
+                 None)
+    others = sorted((m for m in rows if not str(m[3] or "").endswith("_scoped")), key=lambda m: m[1])
+    parts = []
+    if fable:
+        name, left, reset = fable
+        parts.append("%s %d%% left%s" % (name, left, ", resets %s" % u.clock(reset, now) if reset and left else
+                                         ", back %s" % u.clock(reset, now) if reset else ""))
+    for name, left, reset, _ in others[:2 if not fable else 1]:
+        if left <= 0 and reset:
+            parts.append("%s used up, back %s" % (name, u.clock(reset, now)))
+        else:
+            parts.append("%s %d%%" % (name, left))
+    if not room and fable and fable[1] > 0:
+        parts.append("(the weekly limit blocks Fable)")
+    text = " · ".join(parts) or "no limits"
+    return text + (" · cached %s ago" % u.duration(now - saved_at) if saved_at is not None else "")
+
+
+def ranked(accounts, now, u):
+    """[(key, room, entry, result)] best first, for one agent's accounts."""
+    out = []
+    for entry, result in accounts:
+        usage, saved_at, _ = result
+        key, room = rank(usage, saved_at, now, u)
+        out.append((key, room, entry, result))
+    return sorted(out, key=lambda a: a[0])
+
+
+def place_name(agent, profile, sessions):
+    """How hatcheck move names a profile or home: default, NAME, codex, codex:NAME, or a path."""
+    home = os.path.join(sessions.HOME, ".codex" if agent == "codex" else ".claude")
+    if sessions.same_folder(profile, home):
+        return "codex" if agent == "codex" else "default"
+    parent, base = os.path.split(profile.rstrip("/" + os.sep))
+    prefix = os.path.basename(home) + "-"
+    if sessions.same_folder(parent, sessions.HOME) and base.startswith(prefix):
+        return ("codex:" if agent == "codex" else "") + base[len(prefix):]
+    return profile
+
+
+def main(argv=None, prog=None):
+    parser = argparse.ArgumentParser(prog=prog, description="Which account to use now, and where to carry a session. "
+                                                            "Advice only: it never starts, moves or switches anything.")
+    parser.add_argument("--for", dest="session", metavar="SESSION",
+                        help="where to carry this session: the hatcheck move command for the best other account")
+    parser.add_argument("--cached", action="store_true",
+                        help="don't call the APIs; use the snapshots Claude Code and Codex last saved")
+    args = parser.parse_args(argv)
+
+    sessions = load_sibling("hatcheck_sessions", "sessions.py")
+    u = sessions.load_usage_module()
+    if not u:
+        sys.exit("hatcheck best needs usage.py in its folder")
+    ansi = u.setup_console()
+    color = sys.stdout.isatty() and not os.environ.get("NO_COLOR") and ansi
+    paint = (lambda code, s: "\033[%sm%s\033[0m" % (code, s) if code else s) if color else (lambda code, s: s)
+    show = sessions.shell_path
+    now = time.time()
+    loaded = u.load_usage(sessions.find_profiles(), args.cached, sessions.find_codex_homes())
+    by_agent = {"claude": ranked([a for a in loaded if not a[0].get("codex")], now, u),
+                "codex": ranked([a for a in loaded if a[0].get("codex")], now, u)}
+
+    if args.session:
+        return carry(args, sessions, u, by_agent, now, show, (parser.prog or "hatcheck").split()[0])
+
+    for agent, title in (("claude", "Claude Code, best first"), ("codex", "Codex, best first")):
+        accounts = by_agent[agent]
+        if not accounts:
+            continue
+        print(paint("1", title) + (paint("2", " (sorted by Fable, as hatcheck usage sorts)") if agent == "claude" else ""))
+        rows = []
+        for n, (key, room, entry, (usage, saved_at, why)) in enumerate(accounts, 1):
+            names = ", ".join(show(p) for p in entry["profiles"])
+            rows.append(("%d." % n if key[0] < 3 else " -", names, summary(usage, saved_at, why, now, u, room),
+                         sessions.start_command(agent, entry["profiles"][0]), room))
+        width = max(len(r[1]) for r in rows)
+        text_width = max(len(r[2]) for r in rows)
+        for number, names, text, command, room in rows:
+            print("  %s %s  %s  %s" % (number.rjust(3), paint("1" if room else "2", names.ljust(width)),
+                                      paint("" if room else "2", text.ljust(text_width)), paint("36", "→ " + command)))
+    me = (parser.prog or "hatcheck best").split()[0]
+    print(paint("2", "Advice only: nothing is started, moved or switched. %s best --for <session> says where "
+                     "to carry a session." % me))
+
+
+def carry(args, sessions, u, by_agent, now, show, me):
+    """--for: the best other account for a session of the same agent, as a hatcheck move command."""
+    copies = sessions.session_copies(args.session)
+    if not copies:
+        sys.exit("No session starting with %s" % args.session)
+    if len(copies) > 1:
+        sys.exit("%s matches %d sessions; give more of the ID" % (args.session, len(copies)))
+    ((agent, sid), where), = copies.items()
+    found = [s for s in (sessions.summarize(agent, p, f) for p, f in where) if s]
+    if not found:
+        sys.exit("Session %s holds no conversation" % sid[:8])
+    s = max(found, key=lambda s: (s["when"], s.get("canonical", True), s["size"]))
+    accounts = by_agent[agent]
+    mine = next((a for a in accounts if any(sessions.same_folder(p, s["profile"]) for p in a[2]["profiles"])), None)
+    if mine:
+        _, room, entry, (usage, saved_at, why) = mine
+        state = summary(usage, saved_at, why, now, u, room)
+    else:
+        state = "no usage data"
+    print('Session %s "%s" is in %s: %s.' % (sid[:8], sessions.truncate(s["title"], 60), show(s["profile"]), state))
+    best = next((a for a in accounts if a[1] and a is not mine), None)
+    if mine and accounts and mine[1] and accounts.index(mine) < (accounts.index(best) if best else len(accounts)):
+        print("Its own account is the best one now; resume it there with:")
+        if s.get("cwd"):
+            print("  cd " + show(s["cwd"]))
+        print("  " + sessions.session_command(s, False))
+        return
+    if best is None:
+        print("No other %s account has room now." % ("Codex" if agent == "codex" else "Claude Code"))
+        return 1
+    _, _, entry, (usage, saved_at, why) = best
+    dest = entry["profiles"][0]
+    print("Carry it to %s: %s." % (show(dest), summary(usage, saved_at, why, now, u, True)))
+    print("  %s move %s %s --from %s" % (me, sid[:8], place_name(agent, dest, sessions),
+                                               place_name(agent, s["profile"], sessions)))
+    print("It prints the command that resumes it there, and offers to run it.")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hatcheck/bind.py

@@ -0,0 +1,354 @@
+#!/usr/bin/env python3
+"""Tie a folder to a profile, so work there happens under the right account.
+
+Usage:
+    hatcheck bind PROFILE [FOLDER] [--codex HOME]  bind FOLDER (this one by default) and
+                                                   everything under it
+    hatcheck bind                                  what this folder is bound to
+    hatcheck bind --list                           every bound folder
+    hatcheck bind --hook                           warn when Claude Code or Codex starts in a
+                                                   bound folder under another profile
+    hatcheck unbind [FOLDER]                       remove a folder's binding
+    hatcheck unbind --hook                         remove that warning again
+
+  PROFILE : NAME for ~/.claude-NAME, default for ~/.claude, or a path. The folder's
+            Codex home is the one by the same name, ~/.codex-NAME (~/.codex for
+            default), when there is one.
+  --codex : the Codex home to bind instead: NAME for ~/.codex-NAME, default for
+            ~/.codex, or a path. Without PROFILE it binds just the Codex home.
+
+Bindings live in your own config, ~/.config/hatcheck/bindings.json
+(%APPDATA%\\hatcheck\\bindings.json on Windows), not in the repo, so profile names
+don't end up in git. The deepest bound folder wins, and folders are compared once
+symlinks are resolved.
+
+cl and cx use them: without a profile name in a bound folder, cl --resume <id>
+means cl work --resume <id>, and cx resume <id> means cx work resume <id>. The
+session list marks a session that ran in a bound folder under another profile,
+"⚠ folder bound to ~/.claude-work", so it's easy to spot and hatcheck move.
+
+--hook adds a SessionStart hook to every Claude Code profile's settings.json and
+every Codex home's hooks.json, which runs hatcheck bind --check. When a session
+starts in a bound folder under another profile, Claude Code or Codex shows a
+warning that names the folder's profile and the command to use. It only warns;
+nothing is blocked. Codex runs a new hook only once you trust it, with /hooks in
+codex. Claude Code shows the warning in its interactive mode, not with claude -p.
+
+This script loads sessions.py, so keep the two in one folder.
+"""
+import argparse
+import importlib.util
+import json
+import os
+import shlex
+import shutil
+import sys
+
+HOOK = "bind --check"  # in the hook's command, to find it again
+
+
+def load_sessions():
+    sys.dont_write_bytecode = True  # leave no __pycache__ folder beside the scripts
+    path = os.path.join(os.path.dirname(os.path.realpath(__file__)), "sessions.py")
+    spec = importlib.util.spec_from_file_location("hatcheck_sessions", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def write_json(path, data):
+    """Write JSON whole, under a temporary name until it's complete."""
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp = path + ".hatcheck-tmp"
+    with open(tmp, "w", encoding="utf-8", newline="\n") as fh:
+        json.dump(data, fh, ensure_ascii=False, indent=2)
+        fh.write("\n")
+    os.replace(tmp, path)
+
+
+def save_bindings(sessions, bindings):
+    write_json(sessions.bindings_path(), {"version": 1, "folders": dict(sorted(bindings.items()))})
+
+
+def name_of(sessions, agent, spec):
+    """(name to keep, folder) for a PROFILE or --codex argument: default, a NAME or a path."""
+    if spec == "default" or ("/" not in spec and os.sep not in spec and not spec.startswith("~")):
+        return spec, sessions.profile_folder(agent, spec)
+    path = os.path.abspath(os.path.expanduser(spec))
+    return path, path
+
+
+def describe(sessions, binding):
+    show = sessions.shell_path
+    parts = ["%s %s" % (label, show(sessions.profile_folder(agent, binding[agent])))
+             for agent, label in (("claude", "Claude Code"), ("codex", "Codex")) if binding.get(agent)]
+    return " · ".join(parts) or "nothing"
+
+
+def bind(args, sessions):
+    show = sessions.shell_path
+    folder = os.path.realpath(os.path.expanduser(args.folder or os.getcwd()))
+    if not os.path.isdir(folder):
+        sys.exit("%s isn't a folder" % show(folder))
+    bindings = sessions.load_bindings()
+    old = bindings.get(folder) or {}
+    binding = {} if args.profile else {k: v for k, v in old.items() if k == "claude"}
+    notes = []
+    if args.profile:
+        name, path = name_of(sessions, "claude", args.profile)
+        if not os.path.isdir(path):
+            sys.exit("%s isn't a profile folder. Sign in there first, e.g. with: %s"
+                     % (show(path), "claude" if name == "default" else "cl " + name))
+        binding["claude"] = name
+    if args.codex:
+        name, path = name_of(sessions, "codex", args.codex)
+        if not os.path.isdir(path):
+            sys.exit("%s isn't a Codex home. Sign in there first, e.g. with: %s"
+                     % (show(path), "codex login" if name == "default" else "cx %s login" % name))
+        binding["codex"] = name
+    elif args.profile and binding["claude"] == args.profile and not any(c in args.profile for c in "/" + os.sep):
+        path = sessions.profile_folder("codex", args.profile)  # the home named like the profile
+        if os.path.isdir(path):
+            binding["codex"] = args.profile
+        else:
+            notes.append("Codex isn't bound: there's no %s (add --codex NAME for another home)." % show(path))
+    bindings[folder] = binding
+    save_bindings(sessions, bindings)
+    print("Bound %s and everything under it: %s." % (show(folder), describe(sessions, binding)))
+    for note in notes:
+        print(note)
+    print("Here, %s." % " and ".join(text for agent, text in (
+        ("claude", "cl --resume <id> means %s --resume <id>" % sessions.start_command("claude", sessions.profile_folder(
+            "claude", binding.get("claude") or "default"))),
+        ("codex", "cx resume <id> means %s resume <id>" % sessions.start_command("codex", sessions.profile_folder(
+            "codex", binding.get("codex") or "default")))) if binding.get(agent)))
+    if not any(has_hook(read_settings(path)[0]) for _, _, path in hook_files(sessions)):
+        print("hatcheck bind --hook adds a warning to Claude Code when a session starts here under another profile.")
+
+
+def show_here(sessions):
+    show = sessions.shell_path
+    bindings = sessions.load_bindings()
+    folder = sessions.bound_folder(os.getcwd(), bindings)
+    if not folder:
+        print("This folder isn't bound. Bind it with: hatcheck bind <profile>")
+        return
+    where = "This folder" if sessions.same_folder(folder, os.getcwd()) else "This folder is under %s, which" % show(folder)
+    print("%s is bound to %s." % (where, describe(sessions, bindings[folder])))
+
+
+def list_bindings(sessions):
+    show = sessions.shell_path
+    bindings = sessions.load_bindings()
+    if not bindings:
+        print("No folders are bound. Bind this one with: hatcheck bind <profile>")
+        return
+    print("Bound folders, from %s:" % show(sessions.bindings_path()))
+    width = max(len(show(f)) for f in bindings)
+    for folder in sorted(bindings, key=str.lower):
+        missing = "" if os.path.isdir(folder) else "  (folder missing)"
+        print("  %s  %s%s" % (show(folder).ljust(width), describe(sessions, bindings[folder]), missing))
+
+
+def which(args, sessions):
+    """For cl and cx: the name the folder (this one by default) is bound to, or exit 1."""
+    bindings = sessions.load_bindings()
+    folder = sessions.bound_folder(os.path.expanduser(args.profile or os.getcwd()), bindings)
+    name = bindings[folder].get(args.which) if folder else None
+    if not isinstance(name, str) or not name:
+        return 1
+    print(name)
+    return 0
+
+
+# The warning hook: in each Claude Code profile's settings.json, and each Codex home's hooks.json.
+
+def hook_command():
+    """How Claude Code and Codex run the hook: hatcheck from your PATH, or this Python and hatcheck.py."""
+    quote = (lambda s: '"%s"' % s) if os.name == "nt" else shlex.quote
+    exe = shutil.which("hatcheck")
+    if exe:
+        return "%s %s" % (quote(exe), HOOK)
+    script = os.path.join(os.path.dirname(os.path.dirname(os.path.realpath(__file__))), "hatcheck.py")
+    return "%s %s %s" % (quote(sys.executable), quote(script), HOOK)
+
+
+def hook_files(sessions):
+    """(agent, profile or home, the file its hooks are in) for every Claude Code profile and Codex home."""
+    return [("claude", p, os.path.join(p, "settings.json")) for p in sessions.find_profiles()] + \
+        [("codex", h, os.path.join(h, "hooks.json")) for h in sessions.find_codex_homes()]
+
+
+def read_settings(path):
+    """(the JSON object in path, None), {} when there's no file, or (None, why not)."""
+    if not os.path.exists(path):
+        return {}, None
+    name = os.path.basename(path)
+    try:
+        with open(path, encoding="utf-8") as fh:
+            settings = json.load(fh)
+    except (OSError, ValueError) as e:
+        return None, "can't read its %s (%s)" % (name, e.strerror if isinstance(e, OSError) else "not valid JSON")
+    return (settings, None) if isinstance(settings, dict) else (None, "its %s isn't a JSON object" % name)
+
+
+def ours(hook):
+    command = hook.get("command") if isinstance(hook, dict) else None
+    return isinstance(command, str) and HOOK in command and "hatcheck" in command
+
+
+def has_hook(settings):
+    entries = ((settings or {}).get("hooks") or {}).get("SessionStart") if isinstance(settings, dict) else None
+    return any(ours(h) for e in entries or [] if isinstance(e, dict) for h in e.get("hooks") or [])
+
+
+def add_hooks(sessions):
+    show, command, codex = sessions.shell_path, hook_command(), False
+    for agent, folder, path in hook_files(sessions):
+        settings, why = read_settings(path)
+        if settings is None:
+            print("  %s  skipped: %s" % (show(folder), why))
+            continue
+        if has_hook(settings):
+            print("  %s  already has it" % show(folder))
+            continue
+        hooks = settings.setdefault("hooks", {})
+        if not isinstance(hooks, dict) or not isinstance(hooks.setdefault("SessionStart", []), list):
+            print("  %s  skipped: its hooks aren't in the usual form" % show(folder))
+            continue
+        hooks["SessionStart"].append({"hooks": [{"type": "command", "command": command + (" codex" * (agent == "codex"))}]})
+        write_json(path, settings)
+        print("  %s  added, in %s" % (show(folder), os.path.basename(path)))
+        codex |= agent == "codex"
+    print("They run: %s (with codex after it for Codex)" % command)
+    print("Claude Code and Codex warn when a session starts in a bound folder under another profile. "
+          "hatcheck unbind --hook removes them.")
+    if codex:
+        print("Codex runs a new hook only once you trust it: in each Codex home, open /hooks in codex (or cx <name>) "
+              "and trust it.")
+
+
+def remove_hooks(sessions):
+    show = sessions.shell_path
+    for agent, folder, path in hook_files(sessions):
+        settings, why = read_settings(path)
+        if not has_hook(settings):
+            continue
+        hooks = settings["hooks"]
+        kept = []
+        for entry in hooks["SessionStart"]:
+            if isinstance(entry, dict) and isinstance(entry.get("hooks"), list):
+                entry["hooks"] = [h for h in entry["hooks"] if not ours(h)]
+                if not entry["hooks"]:
+                    continue
+            kept.append(entry)
+        hooks["SessionStart"] = kept
+        if not kept:
+            del hooks["SessionStart"]
+        if not hooks:
+            del settings["hooks"]
+        if agent == "codex" and not settings:
+            os.remove(path)  # hooks.json held nothing else
+        else:
+            write_json(path, settings)
+        print("  %s  removed" % show(folder))
+    print("No profile or home runs the hook now.")
+
+
+def check(sessions, agent):
+    """Run by the SessionStart hook in Claude Code, or in Codex (agent codex): when the
+    session's folder is bound to another profile or home, have it show a warning. Never
+    blocks, and stays quiet on any error."""
+    try:
+        data = json.loads(sys.stdin.read() or "{}")
+    except (ValueError, UnicodeError):
+        return 0
+    if not isinstance(data, dict):
+        return 0
+    show = sessions.shell_path
+    cwd = data.get("cwd") or os.getcwd()
+    variable, default = ("CODEX_HOME", ".codex") if agent == "codex" else ("CLAUDE_CONFIG_DIR", ".claude")
+    current = os.path.expanduser(os.environ.get(variable) or os.path.join(sessions.HOME, default))
+    bindings = sessions.load_bindings()
+    folder = sessions.bound_folder(cwd, bindings)
+    name = bindings[folder].get(agent) if folder else None
+    if not isinstance(name, str) or not name:
+        return 0
+    want = sessions.profile_folder(agent, name)
+    if sessions.same_folder(want, current):
+        return 0
+    start, sid = sessions.start_command(agent, want), data.get("session_id") or ""
+    if data.get("source") == "resume" and sid:
+        if agent == "codex":
+            to = name if any(c in name for c in "/" + os.sep) else "codex" if name == "default" else "codex:" + name
+            resume = sessions.codex_command(want, "resume " + sid, False)
+        else:
+            to, resume = name, sessions.claude_command(want, "--resume " + sid, False)
+        todo = "Quit, then carry this session there with: hatcheck move %s %s, and resume it with %s" % (
+            sid[:8], to, resume)
+    else:
+        todo = "Quit and run %s here instead" % start
+    message = "hatcheck: %s is bound to %s, but this session runs in %s. %s." % (
+        show(folder), show(want), show(current), todo)
+    print(json.dumps({"systemMessage": message}))
+    return 0
+
+
+def main(argv=None, prog=None):
+    parser = argparse.ArgumentParser(prog=prog, description="Tie a folder to a profile, so cl and cx pick it there and "
+                                                            "the session list flags work done under another one.")
+    parser.add_argument("profile", nargs="?", help="NAME for ~/.claude-NAME, default for ~/.claude, or a path")
+    parser.add_argument("folder", nargs="?", help="the folder to bind (default: this one)")
+    parser.add_argument("--codex", metavar="HOME", help="the Codex home to bind: NAME for ~/.codex-NAME, default for "
+                                                        "~/.codex, or a path (default: the one named like PROFILE)")
+    parser.add_argument("--list", action="store_true", help="list every bound folder")
+    parser.add_argument("--hook", action="store_true", help="warn in Claude Code and Codex when a session starts in a "
+                                                            "bound folder under another profile")
+    parser.add_argument("--which", nargs="?", const="claude", choices=("claude", "codex"),
+                        help=argparse.SUPPRESS)  # for cl and cx: the name bound to FOLDER, given as PROFILE
+    parser.add_argument("--check", nargs="?", const="claude", choices=("claude", "codex"),
+                        help=argparse.SUPPRESS)  # run by the hook, in Claude Code or in Codex
+    args = parser.parse_args(argv)
+    sessions = load_sessions()
+    if args.check:
+        return check(sessions, args.check)
+    if args.which:
+        return which(args, sessions)
+    usage = sessions.load_usage_module()
+    if usage:
+        usage.setup_console()  # UTF-8 output on Windows
+    if args.list:
+        return list_bindings(sessions)
+    if args.hook:
+        return add_hooks(sessions)
+    if args.profile or args.codex:
+        return bind(args, sessions)
+    return show_here(sessions)
+
+
+def unbind_main(argv=None, prog=None):
+    parser = argparse.ArgumentParser(prog=prog, description="Remove a folder's binding, or the warning hook.")
+    parser.add_argument("folder", nargs="?", help="the bound folder (default: this one)")
+    parser.add_argument("--hook", action="store_true", help="remove the warning hook from every profile")
+    args = parser.parse_args(argv)
+    sessions = load_sessions()
+    show = sessions.shell_path
+    if args.hook:
+        return remove_hooks(sessions)
+    folder = os.path.realpath(os.path.expanduser(args.folder or os.getcwd()))
+    bindings = sessions.load_bindings()
+    key = next((f for f in bindings if sessions.same_folder(f, folder)), None)
+    if key:
+        binding = bindings.pop(key)
+        save_bindings(sessions, bindings)
+        print("Unbound %s (it was bound to %s)." % (show(folder), describe(sessions, binding)))
+        return 0
+    parent = sessions.bound_folder(folder, bindings)
+    if parent:
+        sys.exit("%s isn't bound itself; it's under %s, which is: hatcheck unbind %s"
+                 % (show(folder), show(parent), show(parent)))
+    sys.exit("%s isn't bound" % show(folder))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hatcheck/cli.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""hatcheck: Claude Code and Codex accounts on one computer, each kept apart. Lists
+recent sessions with the command that resumes each one and what's left of each
+plan, and carries sessions between accounts and agents.
+
+Usage:
+    hatcheck [sessions] [HOURS] ...    recent sessions in every profile and home, with
+                                       resume commands and plan usage (the default)
+    hatcheck usage ...                 plan usage left for every profile and home
+    hatcheck where SESSION             where a session is stored, by its ID or the start of it
+    hatcheck move SESSION PROFILE ...  copy a session to another profile or home, or convert
+                                       it between Claude Code and Codex
+    hatcheck open [SESSION] ...        resume a session in a new terminal, in its folder
+    hatcheck show SESSION              a session's conversation, read-only
+    hatcheck best [--for SESSION]      which account to use now, or to carry a session to
+    hatcheck bind PROFILE ...          tie a folder to a profile, for cl, cx and the list
+    hatcheck unbind [FOLDER]           untie it again
+    hatcheck desktop ...               Claude Desktop instances on macOS: list, open, make one
+    hatcheck provider ...              the Z.ai and Kimi keys and models behind claude-z,
+                                       claude-k, cl -z and cl -k
+
+hatcheck, usage, where, show, desktop and move take --json, for scripts, status bars
+and the desktop app.
+
+`hatcheck SUBCOMMAND --help` lists a subcommand's options, and hatcheck --version
+says which version this is. hat is the short name: hat usage is hatcheck usage,
+and so on. cl and cx run Claude Code and Codex with a profile.
+
+The subcommands are the files in the hatcheck/ folder: this one, cli.py, runs them.
+"""
+import importlib.util
+import os
+import re
+import sys
+
+HERE = os.path.dirname(os.path.realpath(__file__))
+SUBCOMMANDS = ("sessions", "usage", "where", "move", "open", "show", "best", "bind", "unbind", "desktop",
+               "provider")
+
+
+def load(name):
+    """A subcommand's module, from this folder."""
+    sys.dont_write_bytecode = True  # leave no __pycache__ folder beside the scripts
+    spec = importlib.util.spec_from_file_location("hatcheck_" + name, os.path.join(HERE, name + ".py"))
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def version():
+    with open(os.path.join(HERE, "__init__.py"), encoding="utf-8") as fh:
+        return re.search(r'__version__ = "([^"]+)"', fh.read()).group(1)
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else list(argv)
+    # The name it was run by, for its messages: hat, the short name, or hatcheck. A link
+    # or command named hat says so in sys.argv[0]; install.ps1's hat.cmd passes --as hat.
+    name = os.path.splitext(os.path.basename(sys.argv[0]))[0]
+    if len(argv) >= 2 and argv[0] == "--as":
+        name, argv = argv[1], argv[2:]
+    me = "hat" if name == "hat" else "hatcheck"
+    if argv and argv[0] in SUBCOMMANDS:
+        command = argv.pop(0)
+        prog = me + " " + command
+    elif argv and argv[0] in ("-h", "--help", "help"):
+        if me == "hat":
+            print("hat is the short name for hatcheck.\n")
+        print(__doc__.strip())
+        return 0
+    elif argv and argv[0] in ("-V", "--version"):
+        print("%s %s" % (me, version()))
+        return 0
+    elif argv and not argv[0].startswith("-") and not re.fullmatch(r"\d+(\.\d+)?[hd]?", argv[0].lower()):
+        sys.stderr.write("%s: there's no %r subcommand; see %s --help\n" % (me, argv[0], me))
+        return 2
+    else:  # options or HOURS: the session list
+        command, prog = "sessions", me
+    return load(command).main(argv, prog)
+
+
+if __name__ == "__main__":
+    sys.exit(main())