claudehop-cli 1.4.0__py3-none-any.whl

claudehop.py

@@ -0,0 +1,1491 @@
+#!/usr/bin/env python3
+"""claudehop - hop Claude Code between several Claude accounts.
+
+To switch accounts, run `hop` and pick one. That is the whole tool.
+
+  hop                  show your accounts, pick one to hop to
+  hop <name>           hop straight to that one
+  hop add <name>       log in as a new account and save it
+
+A hop takes effect for the next `claude` you start. Sessions already running
+keep the account they began with.
+
+Now and then:
+
+  hop whoami           who is logged in right now (asks the API)
+  hop save <name>      save a login you did by hand, under a name
+  hop list --long      token expiry and when each account was saved
+  hop rm <name>        delete a saved account (does not log you out)
+  hop rename <old> <new>
+  hop doctor [--fix]   check the setup, repair what it can
+  hop shell-init       shell glue for a pip install: eval "$(claudehop shell-init)"
+
+Flags:
+
+  -y, --yes            never prompt; also overrides the running-session stop
+  --verify             check saved tokens against the API
+  --long               more columns in the listing
+  --json               machine-readable output
+  --no-color           plain text
+  -V, --version        print the version
+
+Also accepted, for scripts and old habits: `use`/`switch` (what `hop <name>`
+does), `ls`, `active` (print the active name, no network), `sync` (write the live
+login back to its file), `--no-sync`, and the pre-1.2.0 names `claude-acct` and
+`cacct`.
+
+How it works: Claude Code keeps the live login under the "claudeAiOauth" key of
+its credential store - ~/.claude/.credentials.json on Linux, the login keychain
+on macOS. This tool keeps one saved copy of that block per account in
+~/.claude/accounts/<name>.json and swaps the active one in and out. Everything
+else in the store, including your MCP server logins, is left alone. Email and
+plan are re-fetched from the API by Claude Code at startup, so swapping the
+credential is the entire job.
+
+Environment: CLAUDE_CONFIG_DIR (default ~/.claude), CLAUDE_ACCOUNTS_DIR
+(default <config>/accounts), CLAUDE_HOP_BACKEND (auto|file|keychain),
+CLAUDE_HOP_OFFLINE=1 to never call the API.
+"""
+
+from __future__ import annotations
+
+import binascii
+import getpass
+import json
+import os
+import re
+import shutil
+import signal
+import subprocess
+import sys
+import textwrap
+import time
+
+VERSION = "1.4.0"
+PROG = "claudehop"
+
+
+def env(*names: str) -> str | None:
+    """First of these environment variables that is set and non-empty.
+
+    The tool was called claude-acct before 1.2.0, so the old CLAUDE_ACCT_*
+    names are still honoured everywhere the new ones are.
+    """
+    for n in names:
+        v = os.environ.get(n)
+        if v:
+            return v
+    return None
+
+
+HOME = os.path.expanduser("~")
+CLAUDE_DIR = env("CLAUDE_CONFIG_DIR") or os.path.join(HOME, ".claude")
+CREDS = os.path.join(CLAUDE_DIR, ".credentials.json")
+ACCOUNTS = env("CLAUDE_ACCOUNTS_DIR") or os.path.join(CLAUDE_DIR, "accounts")
+ACTIVE_PTR = os.path.join(ACCOUNTS, "active")
+LOCK_PATH = os.path.join(ACCOUNTS, ".lock")
+PROFILE_URL = "https://api.anthropic.com/api/oauth/profile"
+
+# What Claude Code calls its keychain item on macOS.
+KEYCHAIN_SERVICE = "Claude Code-credentials"
+
+OAUTH_KEY = "claudeAiOauth"
+API_TIMEOUT = float(env("CLAUDE_HOP_TIMEOUT", "CLAUDE_ACCT_TIMEOUT") or 10.0)
+OFFLINE = bool(env("CLAUDE_HOP_OFFLINE", "CLAUDE_ACCT_OFFLINE"))
+
+# Temp files this tool writes; the second is what versions before 1.2.0 left.
+TMP_MARKERS = (".tmp-claudehop", ".tmp-claude-acct")
+
+USAGE_EXIT = 2
+
+_ANSI = re.compile(r"\033\[[0-9;]*m")
+
+
+def _use_color() -> bool:
+    if "--no-color" in sys.argv or os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("CLICOLOR_FORCE"):
+        return True
+    return sys.stdout.isatty()
+
+
+BOLD, DIM, GREEN, YELLOW, RED, CYAN, OFF = (
+    ("\033[1m", "\033[2m", "\033[32m", "\033[33m", "\033[31m", "\033[36m", "\033[0m")
+    if _use_color()
+    else ("", "", "", "", "", "", "")
+)
+
+
+def die(msg: str, code: int = 1):
+    print(f"{RED}error:{OFF} {msg}", file=sys.stderr)
+    sys.exit(code)
+
+
+def info(msg: str):
+    print(msg, file=sys.stderr)
+
+
+def visible_len(s: str) -> int:
+    """Width of a string once the colour escapes are stripped."""
+    return len(_ANSI.sub("", s))
+
+
+def pad(s: str, width: int) -> str:
+    return s + " " * max(0, width - visible_len(s))
+
+
+# ------------------------------------------------------------------ json files
+
+
+def read_json(path: str) -> dict:
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except FileNotFoundError:
+        return {}
+    except json.JSONDecodeError as e:
+        die(f"{path} is not valid JSON ({e}). Refusing to touch it.")
+
+
+def write_json_secure(path: str, data: dict, keep_backup: bool = False):
+    """Atomic, 0600, fsynced. Optionally keeps a .bak of the previous file."""
+    tmp = f"{path}{TMP_MARKERS[0]}.{os.getpid()}"
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(data, f, indent=2)
+            f.flush()
+            os.fsync(f.fileno())
+        if keep_backup and os.path.exists(path):
+            shutil.copy2(path, path + ".bak")
+            os.chmod(path + ".bak", 0o600)
+        os.replace(tmp, path)
+        os.chmod(path, 0o600)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.remove(tmp)
+        raise
+
+
+# ------------------------------------------------------------ credential store
+#
+# Two backends. On Linux the live login is a JSON file; on macOS it is normally
+# a generic password in the login keychain, and Claude Code falls back to the
+# file when the keychain is unavailable (ssh, no GUI session). We read and write
+# whichever one currently holds the login so we never split it across both.
+
+
+class FileStore:
+    name = "file"
+
+    def __init__(self, path: str = CREDS):
+        self.path = path
+        self.where = path
+
+    def exists(self) -> bool:
+        return os.path.exists(self.path)
+
+    def read(self) -> dict:
+        return read_json(self.path)
+
+    def write(self, doc: dict):
+        os.makedirs(os.path.dirname(self.path) or ".", exist_ok=True)
+        write_json_secure(self.path, doc, keep_backup=True)
+
+
+class KeychainStore:
+    """macOS login keychain, the same item Claude Code writes itself."""
+
+    name = "keychain"
+
+    def __init__(self, service: str = KEYCHAIN_SERVICE, account: str | None = None):
+        self.service = service
+        self.account = account or os.environ.get("USER") or getpass.getuser()
+        self.where = f"keychain item {service!r} (account {self.account})"
+
+    def _security(self, args: list[str]) -> tuple[int, str, str]:
+        p = subprocess.run(
+            ["security", *args],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        return p.returncode, p.stdout, p.stderr
+
+    def exists(self) -> bool:
+        if not shutil.which("security"):
+            return False
+        rc, _, _ = self._security(
+            ["find-generic-password", "-a", self.account, "-s", self.service]
+        )
+        return rc == 0
+
+    def read(self) -> dict:
+        rc, out, err = self._security(
+            ["find-generic-password", "-a", self.account, "-s", self.service, "-w"]
+        )
+        if rc != 0:
+            if "could not be found" in err:
+                return {}
+            die(f"could not read the keychain item: {err.strip() or f'security exited {rc}'}")
+        raw = out.strip()
+        if not raw:
+            return {}
+        # `security` prints the secret as text, but as hex if it is not printable.
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            try:
+                return json.loads(binascii.unhexlify(raw).decode())
+            except Exception:
+                die("the keychain item does not contain the JSON Claude Code expects.")
+
+    def write(self, doc: dict):
+        blob = json.dumps(doc).encode()
+        rc, _, err = self._security(
+            [
+                "add-generic-password",
+                "-U",  # update in place if it already exists
+                "-a", self.account,
+                "-s", self.service,
+                "-X", binascii.hexlify(blob).decode(),
+            ]
+        )
+        if rc != 0:
+            die(f"could not write the keychain item: {err.strip() or f'security exited {rc}'}")
+
+
+def pick_store():
+    want = (env("CLAUDE_HOP_BACKEND", "CLAUDE_ACCT_BACKEND") or "auto").lower()
+    file_store = FileStore()
+    if want == "file":
+        return file_store
+    if want == "keychain":
+        if not shutil.which("security"):
+            die("CLAUDE_HOP_BACKEND=keychain but the `security` command is not available.")
+        return KeychainStore()
+    if want != "auto":
+        die(f"CLAUDE_HOP_BACKEND must be auto, file or keychain (got {want!r})")
+    if sys.platform != "darwin" or not shutil.which("security"):
+        return file_store
+    kc = KeychainStore()
+    # Whichever one actually holds a login wins; a stale empty file must not
+    # shadow a real keychain login, and vice versa.
+    if kc.exists():
+        return kc
+    if file_store.exists() and file_store.read().get(OAUTH_KEY):
+        return file_store
+    return kc
+
+
+STORE = pick_store()
+
+
+def live_oauth() -> dict | None:
+    return STORE.read().get(OAUTH_KEY) or None
+
+
+def set_live_oauth(block: dict):
+    doc = STORE.read()
+    doc[OAUTH_KEY] = block
+    STORE.write(doc)
+
+
+def clear_live_oauth():
+    doc = STORE.read()
+    doc.pop(OAUTH_KEY, None)
+    STORE.write(doc)
+
+
+# ---------------------------------------------------------------------- lock
+#
+# Two `claudehop` runs at once could interleave read-modify-write on the same
+# credential store and lose an account. Cheap to prevent.
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - POSIX only in practice
+    fcntl = None
+
+
+class _Lock:
+    def __init__(self, path: str):
+        self.path = path
+        self.fd = None
+
+    def __enter__(self):
+        if fcntl is None:
+            return self
+        profiles_dir()
+        self.fd = os.open(self.path, os.O_CREAT | os.O_RDWR, 0o600)
+        try:
+            fcntl.flock(self.fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            info(f"{DIM}waiting for another {PROG} to finish...{OFF}")
+            fcntl.flock(self.fd, fcntl.LOCK_EX)
+        return self
+
+    def __exit__(self, *exc):
+        if self.fd is not None:
+            fcntl.flock(self.fd, fcntl.LOCK_UN)
+            os.close(self.fd)
+            self.fd = None
+        return False
+
+
+def lock():
+    return _Lock(LOCK_PATH)
+
+
+# ------------------------------------------------------------------- profiles
+
+
+def profiles_dir() -> str:
+    os.makedirs(ACCOUNTS, mode=0o700, exist_ok=True)
+    if os.stat(ACCOUNTS).st_mode & 0o077:
+        os.chmod(ACCOUNTS, 0o700)
+    return ACCOUNTS
+
+
+def profile_path(name: str) -> str:
+    return os.path.join(profiles_dir(), f"{name}.json")
+
+
+VALID_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+def check_name(name: str) -> str:
+    if not VALID_NAME.match(name) or name in (".", ".."):
+        die(
+            f"'{name}' is not a usable account name. Use letters, digits, dot, "
+            f"dash or underscore, starting with a letter or digit."
+        )
+    return name
+
+
+def list_profiles() -> list[str]:
+    if not os.path.isdir(ACCOUNTS):
+        return []
+    return sorted(
+        f[:-5] for f in os.listdir(ACCOUNTS) if f.endswith(".json") and not f.startswith(".")
+    )
+
+
+def load_profile(name: str) -> dict:
+    p = profile_path(name)
+    if not os.path.exists(p):
+        known = ", ".join(list_profiles()) or "none saved yet"
+        die(f"no saved account called '{name}'. Saved: {known}")
+    return read_json(p)
+
+
+def save_profile(name: str, block: dict, meta: dict | None = None):
+    data = read_json(profile_path(name))
+    data.update(meta or {})
+    data["name"] = name
+    data[OAUTH_KEY] = block
+    data["savedAt"] = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+    write_json_secure(profile_path(name), data)
+
+
+def read_ptr() -> str | None:
+    try:
+        with open(ACTIVE_PTR) as f:
+            ptr = f.read().strip()
+    except OSError:
+        return None
+    return ptr or None
+
+
+def set_active_ptr(name: str):
+    profiles_dir()
+    tmp = f"{ACTIVE_PTR}.tmp-{os.getpid()}"
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as f:
+        f.write(name + "\n")
+    os.replace(tmp, ACTIVE_PTR)
+
+
+def active_name(check_api: bool = False) -> str | None:
+    """Which saved profile the live login belongs to.
+
+    Claude Code rotates the access token every few hours, so a value match only
+    works right after a switch. The pointer file says which account we put there.
+    With check_api=True we confirm the pointer still describes the same account
+    by asking the API for the live token's uuid - used before we overwrite a
+    saved profile with the live block. If the API is unreachable we trust the
+    pointer.
+    """
+    live = live_oauth()
+    if not live:
+        return None
+    tok = live.get("accessToken")
+    for n in list_profiles():
+        if load_profile(n).get(OAUTH_KEY, {}).get("accessToken") == tok:
+            return n
+    ptr = read_ptr()
+    if not ptr or ptr not in list_profiles():
+        return None
+    if check_api:
+        saved_uuid = load_profile(ptr).get("accountUuid")
+        live_uuid = identity(live).get("accountUuid")
+        if saved_uuid and live_uuid and saved_uuid != live_uuid:
+            return None  # someone logged in as a different account behind our back
+    return ptr
+
+
+# ------------------------------------------------------------------------ API
+
+
+_IDENT_CACHE: dict[str, dict] = {}
+
+
+def api_profile(token: str, timeout: float = API_TIMEOUT) -> tuple[int, dict]:
+    import urllib.error
+    import urllib.request
+
+    req = urllib.request.Request(
+        PROFILE_URL,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "anthropic-beta": "oauth-2025-04-20",
+            "Content-Type": "application/json",
+            "User-Agent": f"{PROG}/{VERSION}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return r.status, json.loads(r.read().decode())
+    except urllib.error.HTTPError as e:
+        try:
+            return e.code, json.loads(e.read().decode())
+        except Exception:
+            return e.code, {}
+    except Exception as e:
+        return 0, {"error": str(e)}
+
+
+def identity(block: dict) -> dict:
+    """email / uuid / plan for a credential block, via the API. {} if unreachable."""
+    tok = block.get("accessToken")
+    if not tok:
+        return {}
+    if OFFLINE:
+        return {"tokenState": "not checked"}
+    if tok not in _IDENT_CACHE:
+        _IDENT_CACHE[tok] = _identity_uncached(tok)
+    return _IDENT_CACHE[tok]
+
+
+def _identity_uncached(tok: str) -> dict:
+    status, body = api_profile(tok)
+    if status == 200:
+        a = body.get("account", {})
+        org = body.get("organization", {})
+        # Team/enterprise seats have neither the max nor the pro flag set; the
+        # plan only shows up as the organization type.
+        if a.get("has_claude_max"):
+            plan = "max"
+        elif a.get("has_claude_pro"):
+            plan = "pro"
+        else:
+            plan = (org.get("organization_type") or "-").replace("claude_", "")
+        return {
+            "email": a.get("email"),
+            "accountUuid": a.get("uuid"),
+            "plan": plan,
+            "org": org.get("name"),
+            "tokenState": "ok",
+        }
+    if status == 403:
+        return {"tokenState": "limited-scope"}
+    if status in (401, 400):
+        return {"tokenState": "invalid"}
+    return {"tokenState": f"http {status}" if status else "offline"}
+
+
+def identify_many(blocks: dict[str, dict]) -> dict[str, dict]:
+    """identity() for several accounts at once - one API round trip of latency."""
+    todo = {n: b for n, b in blocks.items() if b.get("accessToken")}
+    if len(todo) < 2 or OFFLINE:
+        return {n: identity(b) for n, b in blocks.items()}
+    from concurrent.futures import ThreadPoolExecutor
+
+    with ThreadPoolExecutor(max_workers=min(8, len(todo))) as pool:
+        list(pool.map(lambda b: identity(b), todo.values()))
+    return {n: identity(b) for n, b in blocks.items()}
+
+
+def humanise(seconds: float) -> str:
+    if seconds < 3600:
+        return f"{int(seconds // 60)}m"
+    if seconds < 86400:
+        return f"{int(seconds // 3600)}h"
+    return f"{int(seconds // 86400)}d"
+
+
+def expiry_note(block: dict) -> str:
+    exp = block.get("expiresAt")
+    if not exp:
+        return "-"
+    left = exp / 1000 - time.time()
+    if left <= 0:
+        return f"{DIM}expired (auto-renews){OFF}"
+    return f"{humanise(left)} left"
+
+
+def refresh_left(block: dict) -> float | None:
+    """Seconds until the refresh token dies, i.e. until a real re-login."""
+    exp = block.get("refreshTokenExpiresAt")
+    if not exp:
+        return None
+    return exp / 1000 - time.time()
+
+
+def token_state(block: dict, ident: dict) -> str:
+    """What --verify should print for one account.
+
+    An access token that has simply aged out reads as `invalid` to the API, but
+    Claude Code renews it from the refresh token on the next start - that is not
+    a broken account, so say so differently.
+    """
+    state = ident.get("tokenState", "?")
+    if state != "invalid":
+        return state
+    exp = block.get("expiresAt")
+    rleft = refresh_left(block)
+    if exp and exp / 1000 <= time.time() and (rleft is None or rleft > 0):
+        return "stale (renews)"
+    return "invalid"
+
+
+
+# A refresh token is good for about 30 days from the login that issued it, and
+# using the account does NOT extend it - measured 2026-08-06 across four accounts,
+# one of which had its access token reissued that morning and still expired 30 days
+# after its first login. So every account needs a real /login roughly monthly, and
+# with several accounts the dates only drift further apart. Two weeks of notice is
+# enough to plan one sitting; one week is not.
+RELOGIN_NOTICE = 14 * 86400
+
+
+def refresh_warning(block: dict) -> str | None:
+    left = refresh_left(block)
+    if left is None:
+        return None
+    if left <= 0:
+        return f"refresh token expired - this account needs `{PROG} add` again"
+    if left < RELOGIN_NOTICE:
+        return f"refresh token expires in {humanise(left)}"
+    return None
+
+
+def relogin_plan(profiles: dict[str, dict]) -> dict | None:
+    """When each account needs a real /login again, and the cheapest day to do it.
+
+    Logging in early resets the whole 30-day window, so doing every account on the
+    day the earliest one comes due collapses them onto a single date - one sitting
+    a month instead of one surprise per account.
+    """
+    due = {
+        n: p.get(OAUTH_KEY, {}).get("refreshTokenExpiresAt", 0) / 1000
+        for n, p in profiles.items()
+        if p.get(OAUTH_KEY, {}).get("refreshTokenExpiresAt")
+    }
+    if not due:
+        return None
+    now = time.time()
+    live = {n: t for n, t in due.items() if t > now}
+    plan = {
+        "accounts": len(due),
+        "expired": sorted(n for n, t in due.items() if t <= now),
+        "first": None,
+        "firstAccounts": [],
+        "last": None,
+        "spreadDays": 0.0,
+    }
+    if live:
+        first, last = min(live.values()), max(live.values())
+        plan["first"] = first
+        # Anything inside a day of the earliest is part of the same sitting.
+        plan["firstAccounts"] = sorted(n for n, t in live.items() if t - first < 86400)
+        plan["last"] = last
+        plan["spreadDays"] = (last - first) / 86400
+    return plan
+
+
+def relogin_lines(plan: dict) -> list[str]:
+    """The `re-login` block for doctor. Empty when there is nothing to say."""
+    day = lambda ts: time.strftime("%Y-%m-%d", time.localtime(ts))  # noqa: E731
+    lines: list[str] = []
+    if plan["expired"]:
+        lines.append(
+            f"expired: {', '.join(plan['expired'])} - `{PROG} add <name>` to sign in again"
+        )
+    if not plan["first"]:
+        return lines
+    head = f"by {day(plan['first'])} ({', '.join(plan['firstAccounts'])})"
+    others = plan["accounts"] - len(plan["firstAccounts"]) - len(plan["expired"])
+    if others <= 0 or plan["spreadDays"] < 1:
+        lines.append(head)
+        return lines
+    rest = "the other one" if others == 1 else f"the other {others}"
+    lines.append(f"{head}; {rest} by {day(plan['last'])}")
+    lines += textwrap.wrap(
+        f"windows are ~30d from login and do not slide, so re-login all "
+        f"{plan['accounts']} on {day(plan['first'])} and they collapse to one date",
+        width=68,
+    )
+    return lines
+
+
+# --------------------------------------------------------------------- checks
+
+
+def running_claude_pids() -> list[int]:
+    """PIDs of other `claude` processes. Best effort, never raises."""
+    me = os.getpid()
+    pids: list[int] = []
+    if os.path.isdir("/proc"):
+        try:
+            entries = os.listdir("/proc")
+        except OSError:
+            entries = []
+        for entry in entries:
+            if not entry.isdigit() or int(entry) == me:
+                continue
+            try:
+                with open(f"/proc/{entry}/cmdline", "rb") as f:
+                    argv0 = f.read().split(b"\0")[0].decode(errors="replace")
+            except OSError:
+                continue
+            if os.path.basename(argv0) in ("claude", "claude.exe"):
+                pids.append(int(entry))
+        return sorted(pids)
+    # macOS and anything else without /proc.
+    if not shutil.which("pgrep"):
+        return []
+    try:
+        out = subprocess.run(
+            ["pgrep", "-x", "claude"], capture_output=True, text=True, timeout=5
+        ).stdout
+    except (OSError, subprocess.SubprocessError):
+        return []
+    for line in out.split():
+        if line.isdigit() and int(line) != me:
+            pids.append(int(line))
+    return sorted(pids)
+
+
+def warn_running():
+    pids = running_claude_pids()
+    if pids:
+        info(
+            f"{YELLOW}note:{OFF} {len(pids)} claude session(s) still running "
+            f"(pid {', '.join(map(str, pids))}). They keep the old account until you restart "
+            f"them, and one of them may rewrite the credential store when its token refreshes. "
+            f"Quit them for a clean switch."
+        )
+
+
+class _TerminalGone(Exception):
+    """SIGHUP/SIGTERM arrived - unwind so the cleanup blocks get to run."""
+
+
+def _guard_child_signals() -> dict:
+    """Make a long interactive child safe to wait on. Returns what to restore.
+
+    Two different problems, both of which lost a finished login:
+
+    * SIGINT. Claude Code uses Ctrl-C to cancel the current turn, not to quit,
+      so the first one must not unwind this process - it would save and exit
+      while `claude` is still running and still writing to the credential store.
+      A shell ignores SIGINT while a foreground child runs; do the same. This
+      has to be a no-op Python handler rather than SIG_IGN, because SIG_IGN
+      survives exec and would leave `claude` itself unable to see Ctrl-C.
+    * SIGHUP/SIGTERM. The default action kills us outright, which skips every
+      cleanup path and drops a credential that has already been issued. Turn
+      them into an exception instead.
+    """
+
+    def ignore(signum, frame):
+        pass
+
+    def bail(signum, frame):
+        raise _TerminalGone(signum)
+
+    old: dict = {}
+    for sig, handler in (
+        (getattr(signal, "SIGINT", None), ignore),
+        (getattr(signal, "SIGHUP", None), bail),
+        (getattr(signal, "SIGTERM", None), bail),
+    ):
+        if sig is None:
+            continue
+        try:
+            old[sig] = signal.signal(sig, handler)
+        except (OSError, ValueError):  # not the main thread, or unsupported here
+            pass
+    return old
+
+
+def _restore_signals(old: dict):
+    for sig, handler in old.items():
+        try:
+            signal.signal(sig, handler)
+        except (OSError, ValueError):
+            pass
+
+
+def confirm(question: str, assume_yes: bool) -> bool:
+    if assume_yes or not sys.stdin.isatty():
+        return True
+    try:
+        return input(f"{question} [y/N] ").strip().lower() in ("y", "yes")
+    except EOFError:
+        return False
+
+
+def slug(email: str) -> str:
+    s = re.sub(r"[^a-z0-9._-]", "-", email.split("@")[0].lower()).strip("-.") or "account"
+    if not VALID_NAME.match(s):
+        s = "account-" + s.lstrip("-.")
+    # An account called `list` would shadow the command of the same name.
+    return f"{s}-acct" if s in COMMANDS else s
+
+
+def stash_live(live: dict) -> str:
+    """Save an unrecognised live login under its own name. Returns that name."""
+    ident = identity(live)
+    name = slug(ident["email"]) if ident.get("email") else f"unsaved-{int(time.time())}"
+    save_profile(name, live, {k: v for k, v in ident.items() if k != "tokenState"})
+    return name
+
+
+def sync_live_before_switch(live: dict) -> str | None:
+    """Never drop a login we cannot get back. Returns the profile it went to."""
+    cur = active_name(check_api=True)
+    if cur:
+        save_profile(cur, live, {})
+        return cur
+    name = stash_live(live)
+    info(f"{DIM}stashed the current login as '{name}' first{OFF}")
+    return name
+
+
+# ------------------------------------------------------------------- commands
+
+
+def print_table(hdr: tuple, rows: list, highlight=()):
+    """Columns wide enough for their widest cell; highlight those row indexes."""
+    w = [max(visible_len(str(r[i])) for r in [hdr, *rows]) for i in range(len(hdr))]
+    print(DIM + "  ".join(pad(str(h), w[i]) for i, h in enumerate(hdr)).rstrip() + OFF)
+    for i, r in enumerate(rows):
+        line = "  ".join(pad(str(c), w[j]) for j, c in enumerate(r)).rstrip()
+        print((GREEN + line + OFF) if i in highlight else line)
+
+
+def cmd_list(verify=False, as_json=False, long_=False, **_):
+    names = list_profiles()
+    live = live_oauth()
+    cur = active_name(check_api=verify)
+    if not names and not as_json:
+        info("No accounts saved yet.")
+        if live:
+            info(f"You are logged in - save this one with:  {PROG} save <name>")
+        else:
+            info(f"Log in with:  {PROG} add <name>")
+        return
+
+    profiles = {n: load_profile(n) for n in names}
+    idents: dict[str, dict] = {}
+    if verify:
+        idents = identify_many({n: p.get(OAUTH_KEY, {}) for n, p in profiles.items()})
+        for n, ident in idents.items():
+            if not ident.get("email"):
+                continue
+            p = profiles[n]
+            fresh = {k: ident[k] for k in ("email", "plan", "accountUuid") if ident.get(k)}
+            if any(p.get(k) != v for k, v in fresh.items()):
+                p.update(fresh)
+                write_json_secure(profile_path(n), p)
+
+    if as_json:
+        print(
+            json.dumps(
+                {
+                    "backend": STORE.name,
+                    "active": cur,
+                    "accounts": [
+                        {
+                            "name": n,
+                            "email": profiles[n].get("email"),
+                            "plan": profiles[n].get("plan"),
+                            "accountUuid": profiles[n].get("accountUuid"),
+                            "savedAt": profiles[n].get("savedAt"),
+                            "active": n == cur,
+                            "expiresAt": profiles[n].get(OAUTH_KEY, {}).get("expiresAt"),
+                            "refreshTokenExpiresAt": profiles[n]
+                            .get(OAUTH_KEY, {})
+                            .get("refreshTokenExpiresAt"),
+                            "tokenState": token_state(
+                                profiles[n].get(OAUTH_KEY, {}), idents[n]
+                            )
+                            if verify
+                            else None,
+                        }
+                        for n in names
+                    ],
+                },
+                indent=2,
+            )
+        )
+        return
+
+    # Default columns answer the only question that matters - which account is
+    # which. Token expiry and save dates needed a paragraph of explanation to be
+    # readable at all, so they moved behind --long. STATE only means something
+    # once we have actually asked the API.
+    hdr = ("", "NAME", "EMAIL", "PLAN")
+    if verify:
+        hdr += ("STATE",)
+    if long_:
+        hdr += ("TOKEN", "SAVED")
+    rows = []
+    for n in names:
+        blk = profiles[n].get(OAUTH_KEY, {})
+        row = (
+            "*" if n == cur else " ",
+            n,
+            profiles[n].get("email") or "?",
+            profiles[n].get("plan") or "?",
+        )
+        if verify:
+            row += (token_state(blk, idents.get(n, {})),)
+        if long_:
+            row += (expiry_note(blk), (profiles[n].get("savedAt") or "")[:10])
+        rows.append(row)
+    print_table(hdr, rows, {i for i, n in enumerate(names) if n == cur})
+
+    for n in names:
+        warn = refresh_warning(profiles[n].get(OAUTH_KEY, {}))
+        if warn:
+            info(f"{YELLOW}note:{OFF} {n}: {warn}")
+    if cur is None and live:
+        info(
+            f"\n{YELLOW}note:{OFF} the current login does not match any saved account. "
+            f"Save it with:  {PROG} save <name>"
+        )
+
+
+def cmd_pick(yes=False, no_sync=False, verify=False, as_json=False, long_=False, **_):
+    """`hop` with nothing after it: show the accounts and offer to switch.
+
+    The tool exists to answer one question - which account? - so ask it, instead
+    of printing a table and making you retype a name out of it. Falls back to a
+    plain listing when there is nothing to choose between, or when stdout is a
+    pipe and there is nobody there to answer.
+    """
+    names = list_profiles()
+    if len(names) < 2 or not (sys.stdin.isatty() and sys.stdout.isatty()):
+        cmd_list(verify=verify, as_json=as_json, long_=long_)
+        return
+
+    profiles = {n: load_profile(n) for n in names}
+    cur = active_name()
+    rows = [
+        (f"{i}. *" if n == cur else f"{i}.", n,
+         profiles[n].get("email") or "?", profiles[n].get("plan") or "?")
+        for i, n in enumerate(names, 1)
+    ]
+    print_table(("", "NAME", "EMAIL", "PLAN"), rows,
+                {i for i, n in enumerate(names) if n == cur})
+    try:
+        answer = input(f"\nhop to which? [1-{len(names)}, Enter to stay] ").strip()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return
+    if not answer:
+        return
+
+    if answer.isdigit() and 1 <= int(answer) <= len(names):
+        chosen = names[int(answer) - 1]
+    else:  # a name, or enough of one to be unambiguous
+        hits = [n for n in names if n == answer] or [n for n in names if n.startswith(answer)]
+        if len(hits) != 1:
+            die(f"'{answer}' is not one of them. Pick a number, or a name.", USAGE_EXIT)
+        chosen = hits[0]
+
+    if chosen == cur:
+        print(f"already on {GREEN}{chosen}{OFF}")
+        return
+    cmd_use(name=chosen, yes=yes, no_sync=no_sync)
+
+
+def cmd_active(as_json=False, **_):
+    cur = active_name()
+    if as_json:
+        print(json.dumps({"active": cur, "backend": STORE.name}))
+    elif cur:
+        print(cur)
+    else:
+        sys.exit(1)
+
+
+def cmd_whoami(as_json=False, **_):
+    live = live_oauth()
+    if not live:
+        if as_json:
+            print(json.dumps({"loggedIn": False, "backend": STORE.name}))
+        else:
+            print("not logged in")
+        sys.exit(1)
+    ident = identity(live)
+    name = active_name(check_api=True)
+    overrides = [
+        v for v in ("ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN") if os.environ.get(v)
+    ]
+    if as_json:
+        print(
+            json.dumps(
+                {
+                    "loggedIn": True,
+                    "backend": STORE.name,
+                    "account": name,
+                    "email": ident.get("email"),
+                    "plan": ident.get("plan") or live.get("subscriptionType"),
+                    "org": ident.get("org"),
+                    "accountUuid": ident.get("accountUuid"),
+                    "tokenState": ident.get("tokenState"),
+                    "expiresAt": live.get("expiresAt"),
+                    "envOverrides": overrides,
+                },
+                indent=2,
+            )
+        )
+        return
+    email = ident.get("email") or "(could not reach the API)"
+    plan = ident.get("plan") or live.get("subscriptionType") or "?"
+    print(
+        f"{BOLD}{email}{OFF}  [{plan}]  saved as: {name or '(unsaved)'}  "
+        f"token: {expiry_note(live)}"
+    )
+    for var in overrides:
+        info(f"{YELLOW}warning:{OFF} ${var} is set in this shell and overrides the saved login.")
+
+
+def cmd_save(name=None, yes=False, **_):
+    live = live_oauth()
+    if not live:
+        die("not logged in - nothing to save. Run `claude` and use /login first.")
+    ident = identity(live)
+    if not name:
+        if not ident.get("email"):
+            die("could not reach the API to name this account automatically - pass a name.")
+        name = slug(ident["email"])
+    check_name(name)
+    if os.path.exists(profile_path(name)) and not confirm(f"overwrite saved account '{name}'?", yes):
+        die("aborted")
+    save_profile(name, live, {k: v for k, v in ident.items() if k != "tokenState"})
+    set_active_ptr(name)
+    print(f"saved {GREEN}{name}{OFF} ({ident.get('email') or 'email unknown'}) -> {profile_path(name)}")
+
+
+def cmd_sync(**_):
+    live = live_oauth()
+    if not live:
+        die("not logged in - nothing to sync.")
+    n = active_name(check_api=True)
+    if not n:
+        die(f"current login is not one of the saved accounts. Use `{PROG} save <name>`.")
+    save_profile(n, live, {})
+    print(f"synced live login into {n}")
+
+
+def cmd_use(name=None, yes=False, no_sync=False, **_):
+    if not name:
+        die(f"usage: {PROG} use <name>", USAGE_EXIT)
+    target = load_profile(name)
+    blk = target.get(OAUTH_KEY)
+    if not blk:
+        die(f"'{name}' has no saved credentials. Re-save it with `{PROG} add {name}`.")
+
+    live = live_oauth()
+    if live and live.get("accessToken") == blk.get("accessToken"):
+        print(f"already on {GREEN}{name}{OFF} ({target.get('email') or '?'})")
+        set_active_ptr(name)
+        return
+
+    if live and not no_sync:
+        sync_live_before_switch(live)
+
+    set_live_oauth(blk)
+    set_active_ptr(name)
+    print(
+        f"switched to {GREEN}{name}{OFF} "
+        f"({target.get('email') or 'email unknown'}, {target.get('plan') or '?'})"
+    )
+    warn = refresh_warning(blk)
+    if warn:
+        info(f"{YELLOW}note:{OFF} {warn}")
+    warn_running()
+    print(f"{DIM}open a new terminal and run `claude` - it will start as this account.{OFF}")
+
+
+def cmd_add(name=None, yes=False, **_):
+    if not name:
+        die(f"usage: {PROG} add <name>", USAGE_EXIT)
+    check_name(name)
+    target = profile_path(name)
+    # Kept in memory so a replace that turns out to be the wrong account can be
+    # undone without leaving a .bak behind for `doctor` to complain about.
+    prior = read_json(target) if os.path.exists(target) else None
+    if prior is not None and not confirm(f"'{name}' already exists - replace it?", yes):
+        die("aborted")
+    if not shutil.which("claude"):
+        die("`claude` is not on your PATH, so I can't drive the login. Install Claude Code first.")
+    if not sys.stdin.isatty():
+        die(f"adding an account needs a terminal - run `{PROG} add {name}` from one.")
+
+    # A running session writes its own refreshed token into the credential store
+    # without warning, which lands the wrong account under `name`. That is much
+    # easier to prevent than to explain afterwards.
+    pids = running_claude_pids()
+    if pids and not yes:
+        die(
+            f"quit your other claude session(s) first - pid {', '.join(map(str, pids))}.\n"
+            f"       While you are logging in, any one of them can write its own token back "
+            f"into the credential store, and '{name}' would end up holding that account "
+            f"instead.\n       Run with --yes to go ahead anyway."
+        )
+
+    live = live_oauth()
+    prev_name = None
+    if live:
+        prev_name = sync_live_before_switch(live)
+        info(f"{DIM}saved the current login ({prev_name}) before logging out{OFF}")
+
+    clear_live_oauth()
+    info(f"\nStarting `claude` with no login. Sign in as the {BOLD}{name}{OFF} account")
+    info("(use /login if it does not prompt), then exit with /exit or Ctrl-D.")
+    info(
+        f"{DIM}Your browser is already signed in as one of your other accounts. Paste the\n"
+        f"login URL into a private window, or you will just re-authorise that one.{OFF}\n"
+    )
+
+    new: dict | None = None
+    persisted = False
+
+    def persist() -> bool:
+        """Write whatever `claude` produced to disk. Idempotent.
+
+        Deliberately does no network call first. Looking the account's email up
+        takes up to CLAUDE_HOP_TIMEOUT seconds, and an interrupt anywhere in that
+        window used to lose a credential that had already been issued - you were
+        left logged in as an account with nothing saved for it. The identity
+        lookup happens after the token is safely on disk; `list --verify` fills
+        in an email that never made it.
+        """
+        nonlocal new, persisted
+        if persisted:
+            return True
+        found = live_oauth()
+        if not found or (live and found.get("accessToken") == live.get("accessToken")):
+            # Nothing new was signed in - put back what was there. Never leave
+            # the user logged out of everything.
+            if live:
+                set_live_oauth(live)
+            return False
+        new = found
+        # A replaced profile must not keep the old account's email and plan
+        # against the new account's token, even if we get killed right here.
+        stale = dict.fromkeys(("email", "plan", "accountUuid", "org")) if prior else {}
+        save_profile(name, found, stale)
+        set_active_ptr(name)
+        persisted = True
+        return True
+
+    old_signals = _guard_child_signals()
+    hung_up = False
+    try:
+        try:
+            subprocess.call(["claude"])
+        except _TerminalGone:
+            hung_up = True
+    finally:
+        try:
+            saved = persist()
+        finally:
+            _restore_signals(old_signals)
+
+    if not saved:
+        info(f"{YELLOW}no new login found after that.{OFF} Nothing saved for '{name}'.")
+        if prior is not None:
+            info(f"The existing '{name}' profile was left as it was.")
+        if live:
+            prev = active_name()
+            info("Your previous login was restored" + (f" ({prev})." if prev else "."))
+        else:
+            info("You were not logged in before either, so you still are not.")
+        sys.exit(1)
+
+    ident = identity(new)
+
+    # A `claude` session that was already running refreshes its own token
+    # straight into the credential store, and that block is not the login we
+    # asked for. Saving it under `name` would file one account's live credential
+    # under another account's name.
+    prev_uuid = (
+        read_json(profile_path(prev_name)).get("accountUuid")
+        if prev_name and prev_name != name
+        else None
+    )
+    if prev_uuid and ident.get("accountUuid") == prev_uuid:
+        if prior is not None:
+            write_json_secure(target, prior)
+        else:
+            os.remove(target)
+        save_profile(prev_name, new, {})  # it is a newer token for that account
+        set_active_ptr(prev_name)
+        die(
+            f"the credential store holds {ident.get('email') or prev_name} again, not a new "
+            f"login - another running claude session refreshed it while we waited. Nothing "
+            f"saved for '{name}'. Quit every claude session, then try again."
+        )
+
+    meta = {k: v for k, v in ident.items() if k != "tokenState"}
+    if meta:
+        save_profile(name, new, meta)
+    print(f"saved and now active: {GREEN}{name}{OFF} ({ident.get('email') or 'email unknown'})")
+    if not ident.get("accountUuid"):
+        info(
+            f"{YELLOW}note:{OFF} could not confirm which account that is, so '{name}' has no "
+            f"email or plan recorded. Fill them in with:  {PROG} list --verify"
+        )
+    if hung_up:
+        info(f"{DIM}(the terminal went away, but the login was saved){OFF}")
+
+
+def cmd_rm(name=None, yes=False, **_):
+    if not name:
+        die(f"usage: {PROG} rm <name>", USAGE_EXIT)
+    load_profile(name)  # existence check
+    if name == active_name():
+        info(
+            f"{YELLOW}note:{OFF} '{name}' is the account you are logged in as right now; "
+            f"deleting the saved copy does not log you out."
+        )
+    if not confirm(f"delete saved account '{name}'?", yes):
+        die("aborted")
+    for f in (profile_path(name), profile_path(name) + ".bak"):
+        if os.path.exists(f):
+            os.remove(f)
+    if read_ptr() == name:
+        os.remove(ACTIVE_PTR)
+    print(f"deleted {name}")
+
+
+def cmd_rename(name=None, new=None, **_):
+    if not name or not new:
+        die(f"usage: {PROG} rename <old> <new>", USAGE_EXIT)
+    check_name(new)
+    data = load_profile(name)
+    if os.path.exists(profile_path(new)):
+        die(f"'{new}' already exists")
+    was_active = read_ptr() == name or active_name() == name
+    data["name"] = new
+    write_json_secure(profile_path(new), data)
+    for f in (profile_path(name), profile_path(name) + ".bak"):
+        if os.path.exists(f):
+            os.remove(f)
+    if was_active:
+        set_active_ptr(new)
+    print(f"renamed {name} -> {new}")
+
+
+def cmd_doctor(fix=False, verify=False, as_json=False, **_):
+    problems: list[dict] = []
+
+    def note(level: str, msg: str, fixed: str | None = None):
+        problems.append({"level": level, "message": msg, "fixed": fixed})
+
+    live = live_oauth()
+    names = list_profiles()
+    profiles = {n: read_json(profile_path(n)) for n in names}
+    plan = relogin_plan(profiles)
+
+    for var in ("ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"):
+        if os.environ.get(var):
+            note("warn", f"${var} is set and overrides the saved login entirely")
+
+    if os.path.isdir(ACCOUNTS):
+        mode = os.stat(ACCOUNTS).st_mode & 0o777
+        if mode & 0o077:
+            if fix:
+                os.chmod(ACCOUNTS, 0o700)
+                note("warn", f"{ACCOUNTS} was {mode:o}", "chmod 700")
+            else:
+                note("error", f"{ACCOUNTS} is mode {mode:o}; it should be 700")
+
+    for n in names:
+        p = profile_path(n)
+        mode = os.stat(p).st_mode & 0o777
+        if mode & 0o077:
+            if fix:
+                os.chmod(p, 0o600)
+                note("warn", f"{p} was {mode:o}", "chmod 600")
+            else:
+                note("error", f"{p} is mode {mode:o}; it should be 600")
+        if not profiles[n].get(OAUTH_KEY, {}).get("accessToken"):
+            note("error", f"'{n}' has no saved credentials; re-add it")
+        warn = refresh_warning(profiles[n].get(OAUTH_KEY, {}))
+        if warn:
+            note("warn", f"{n}: {warn}")
+
+    stale = []
+    if os.path.isdir(ACCOUNTS):
+        stale = [
+            os.path.join(ACCOUNTS, f)
+            for f in os.listdir(ACCOUNTS)
+            if any(m in f for m in TMP_MARKERS) or f.endswith(".json.bak")
+        ]
+    for f in stale:
+        if fix:
+            os.remove(f)
+            note("warn", f"stale file {f}", "removed")
+        else:
+            note("warn", f"stale file {f} (contains an old credential); --fix removes it")
+
+    ptr = read_ptr()
+    if ptr and ptr not in names:
+        note("error", f"active pointer names '{ptr}', which is not a saved account")
+    if live and active_name(check_api=verify) is None:
+        note("warn", f"the live login does not match any saved account; `{PROG} save <name>`")
+    if not live:
+        note("warn", "not logged in right now")
+
+    pids = running_claude_pids()
+    if pids:
+        note("warn", f"{len(pids)} claude session(s) running; they may rewrite the credentials")
+
+    if verify and names:
+        blocks = {n: load_profile(n).get(OAUTH_KEY, {}) for n in names}
+        for n, ident in identify_many(blocks).items():
+            state = token_state(blocks[n], ident)
+            if state in ("ok", "not checked", "stale (renews)", None):
+                continue
+            level = "warn" if state.startswith(("offline", "http")) else "error"
+            note(level, f"'{n}' token state: {state}")
+
+    if as_json:
+        print(
+            json.dumps(
+                {
+                    "backend": STORE.name,
+                    "store": STORE.where,
+                    "configDir": CLAUDE_DIR,
+                    "accountsDir": ACCOUNTS,
+                    "accounts": names,
+                    "active": active_name(),
+                    "reloginPlan": plan,
+                    "problems": problems,
+                },
+                indent=2,
+            )
+        )
+    else:
+        print(f"{BOLD}{PROG} {VERSION}{OFF}")
+        print(f"  backend      {STORE.name} ({STORE.where})")
+        print(f"  config dir   {CLAUDE_DIR}")
+        print(f"  accounts     {ACCOUNTS} ({len(names)} saved)")
+        print(f"  active       {active_name() or '(none)'}")
+        for i, line in enumerate(relogin_lines(plan) if plan else []):
+            print(f"  {'re-login' if i == 0 else '        '}     {line}")
+        print()
+        if not problems:
+            print(f"{GREEN}no problems found{OFF}")
+        for p in problems:
+            colour = RED if p["level"] == "error" else YELLOW
+            suffix = f" {GREEN}[{p['fixed']}]{OFF}" if p["fixed"] else ""
+            print(f"  {colour}{p['level']}{OFF}  {p['message']}{suffix}")
+    if any(p["level"] == "error" and not p["fixed"] for p in problems):
+        sys.exit(1)
+
+
+def cmd_help(**_):
+    print(__doc__.strip())
+
+
+def cmd_version(**_):
+    print(f"{PROG} {VERSION}")
+
+
+# Second names for a command, kept working but not worth offering on TAB.
+ALIASES = {"ls", "current", "switch", "new", "login", "remove", "delete", "mv", "check"}
+
+
+# Verbs and flags worth completing. Built from the tables below at call time, so
+# a new command can't be added without tab-completion following it.
+def _completion_words() -> tuple[str, str]:
+    verbs = " ".join(k for k in COMMANDS if not k.startswith("-") and k not in ALIASES)
+    flags = " ".join(sorted(k for k in FLAGS if k.startswith("--")))
+    return verbs, flags
+
+
+def cmd_shell_init(**_):
+    """Print shell glue for a pip/pipx install: `eval "$(claudehop shell-init)"`.
+
+    The repo installer writes shell/claudehop.sh instead, which also puts
+    ~/.claude/bin on your PATH. A pip install already has the commands on the
+    PATH, so all this adds is the `hop` alias and tab-completion.
+    """
+    verbs, flags = _completion_words()
+    print(
+        textwrap.dedent(
+            f"""\
+            # {PROG} {VERSION} — add to your shell rc:  eval "$({PROG} shell-init)"
+            if [ -n "${{ZSH_VERSION:-}}" ]; then
+              autoload -Uz +X bashcompinit 2>/dev/null && bashcompinit 2>/dev/null
+            fi
+            alias hop='{PROG}'
+            _claudehop_names() {{
+              local d="${{CLAUDE_ACCOUNTS_DIR:-${{CLAUDE_CONFIG_DIR:-$HOME/.claude}}/accounts}}" f n
+              for f in "$d"/*.json; do
+                [ -e "$f" ] || continue
+                n="${{f##*/}}"
+                printf '%s ' "${{n%.json}}"
+              done
+            }}
+            _claudehop_complete() {{
+              local cur prev names
+              cur="${{COMP_WORDS[COMP_CWORD]}}"
+              prev="${{COMP_WORDS[COMP_CWORD-1]}}"
+              names="$(_claudehop_names)"
+              if [ "$COMP_CWORD" -eq 1 ]; then
+                COMPREPLY=($(compgen -W "{verbs} $names" -- "$cur"))
+              else
+                case "$prev" in
+                  use|switch|rm|remove|delete|rename|mv|save|add|new|login)
+                    COMPREPLY=($(compgen -W "$names" -- "$cur")) ;;
+                  *)
+                    COMPREPLY=($(compgen -W "{flags}" -- "$cur")) ;;
+                esac
+              fi
+            }}
+            complete -F _claudehop_complete {PROG} hop 2>/dev/null
+            """
+        ).rstrip()
+    )
+
+
+COMMANDS = {
+    "list": cmd_list, "ls": cmd_list,
+    "use": cmd_use, "switch": cmd_use,
+    "save": cmd_save,
+    "add": cmd_add, "new": cmd_add, "login": cmd_add,
+    "whoami": cmd_whoami, "current": cmd_whoami,
+    "active": cmd_active,
+    "sync": cmd_sync,
+    "rm": cmd_rm, "remove": cmd_rm, "delete": cmd_rm,
+    "rename": cmd_rename, "mv": cmd_rename,
+    "doctor": cmd_doctor, "check": cmd_doctor,
+    "shell-init": cmd_shell_init,
+    "help": cmd_help, "-h": cmd_help, "--help": cmd_help,
+    "version": cmd_version, "-V": cmd_version, "--version": cmd_version,
+}
+
+# Commands that only read; they skip the lock and never touch the store.
+READ_ONLY = {cmd_list, cmd_whoami, cmd_active, cmd_help, cmd_version, cmd_shell_init}
+
+FLAGS = {
+    "-y": "yes", "--yes": "yes",
+    "--verify": "verify",
+    "--long": "long_", "-l": "long_",
+    "--no-sync": "no_sync",
+    "--json": "as_json",
+    "--fix": "fix",
+    "--no-color": "no_color",
+}
+
+
+def main(argv: list[str]):
+    flags = {"yes": False, "verify": False, "long_": False, "no_sync": False,
+             "as_json": False, "fix": False, "no_color": False}
+    args: list[str] = []
+    only_positional = False
+    for a in argv:
+        if only_positional:
+            args.append(a)
+        elif a == "--":
+            only_positional = True
+        elif a in FLAGS:
+            flags[FLAGS[a]] = True
+        elif a.startswith("-") and a not in COMMANDS:
+            die(f"unknown option '{a}'. Try: {PROG} help", USAGE_EXIT)
+        else:
+            args.append(a)
+
+    # Bare `hop` in a terminal asks which account you want; everywhere else -
+    # a pipe, --json, a statusline - it stays a plain listing, and takes no lock.
+    if not args and not flags["as_json"]:
+        if sys.stdin.isatty() and sys.stdout.isatty():
+            with lock():
+                cmd_pick(**flags)
+        else:
+            cmd_list(**flags)
+        return
+
+    cmd = args[0] if args else "list"
+    fn = COMMANDS.get(cmd)
+    if not fn:
+        # `claudehop work` is a shortcut for `claudehop use work`
+        if VALID_NAME.match(cmd) and os.path.exists(profile_path(cmd)):
+            fn, args = cmd_use, ["use", cmd]
+        else:
+            known = ", ".join(list_profiles())
+            hint = f" Saved accounts: {known}." if known else ""
+            die(f"unknown command '{cmd}'. Try: {PROG} help{hint}", USAGE_EXIT)
+    if len(args) > 3:
+        die(f"too many arguments for '{cmd}'", USAGE_EXIT)
+
+    def call():
+        fn(
+            name=args[1] if len(args) > 1 else None,
+            new=args[2] if len(args) > 2 else None,
+            **flags,
+        )
+
+    # `list --verify` writes the refreshed email/plan back, so it needs the lock too.
+    if fn in READ_ONLY and not flags["verify"]:
+        call()
+    else:
+        with lock():
+            call()
+
+
+def _run() -> int:
+    try:
+        main(sys.argv[1:])
+    except SystemExit as e:
+        if isinstance(e.code, int):
+            return e.code
+        return 0 if e.code is None else 1
+    return 0
+
+
+def console_main() -> int:
+    """Entry point for the `claudehop` and `hop` commands, and for `python -m`."""
+    try:
+        code = _run()
+        sys.stdout.flush()
+    except KeyboardInterrupt:
+        code = 130
+    except BrokenPipeError:
+        # `claudehop list | head` — say nothing, leave no traceback.
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        code = 0
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(console_main())