@dst-justin/relay 2.0.2 → 2.1.1

package/README.md

@@ -161,6 +161,38 @@ Prefix commands with `!` to run them inline:
 | `relay version` | Show current version |
 | `relay update` | Check GitHub releases and update to the latest version |
 | `relay uninstall` | Remove relay and all account data (macOS/Linux only) |
+| `relay autoswitch config` | Interactive setup wizard |
+| `relay autoswitch start` | Install and start background daemon |
+| `relay autoswitch stop` | Stop and remove daemon |
+| `relay autoswitch status` | Daemon state and per-account thresholds |
+| `relay autoswitch log` | Recent auto-switch history |
+
+## Autoswitch
+
+relay can automatically switch accounts when a 5-hour usage threshold is hit.
+
+**Setup:**
+
+```bash
+relay autoswitch config   # interactive wizard
+relay autoswitch start    # install daemon (launchd / systemd / cron)
+relay autoswitch status   # verify it's running
+```
+
+**Config file** (`~/.claude-relay/autoswitch.json`):
+
+```json
+{
+  "order": ["work", "personal", "backup"],
+  "thresholds": { "work": 70, "personal": 80 },
+  "poll": { "low_minutes": 10, "high_minutes": 2, "high_threshold": 50 }
+}
+```
+
+- Only accounts listed in `order` with a `thresholds` entry participate.
+- No config file = autoswitch disabled entirely.
+- Manual switches (`!relay work`) are respected until that account hits its threshold.
+- If all accounts are over threshold, relay switches to the least-used one.
 
 ## How It Works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dst-justin/relay",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "description": "Multi-account switcher for Claude Code — instant credential swap across macOS, Linux, and Windows",
   "bin": {
     "relay": "./relay.js"
@@ -10,10 +10,11 @@
     "relay.js",
     "relay.ps1",
     "relay.cmd",
+    "postinstall.js",
     "README.md"
   ],
   "scripts": {
-    "postinstall": "node -e \"if(process.platform!=='win32'){try{require('fs').chmodSync(require('path').join(__dirname,'relay'),'755')}catch(_){}}\""
+    "postinstall": "node -e \"if(process.platform!=='win32'){try{require('fs').chmodSync(require('path').join(__dirname,'relay'),'755')}catch(_){}}\" && node postinstall.js"
   },
   "engines": {
     "node": ">=16"

package/postinstall.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Runs after `npm install -g @dst-justin/relay`.
+// If the npm global bin dir is not in PATH, appends it to shell config files.
+'use strict';
+
+const { execSync } = require('child_process');
+const { existsSync, readFileSync, appendFileSync, mkdirSync, writeFileSync } = require('fs');
+const { join } = require('path');
+const os = require('os');
+
+// ── Windows ───────────────────────────────────────────────────────────────────
+// npm on Windows already manages PATH via the installer; nothing to do here.
+if (process.platform === 'win32') {
+  // Verify relay.js can reach relay.ps1 (sanity check)
+  if (!existsSync(join(__dirname, 'relay.ps1'))) {
+    console.warn('  relay: warning — relay.ps1 not found, Windows support may be broken');
+  }
+  process.exit(0);
+}
+
+// ── Get npm global bin dir ────────────────────────────────────────────────────
+// npm sets npm_config_prefix during install; fall back to `npm prefix -g`
+let prefix = process.env.npm_config_prefix;
+if (!prefix) {
+  try {
+    prefix = execSync('npm prefix -g', { encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
+  } catch (_) {
+    process.exit(0); // can't determine, give up silently
+  }
+}
+const binDir = join(prefix, 'bin');
+
+// Already in PATH — nothing to do
+const pathDirs = (process.env.PATH || '').split(':');
+if (pathDirs.includes(binDir)) process.exit(0);
+
+const home = os.homedir();
+
+// ── POSIX shells: bash / zsh / sh ────────────────────────────────────────────
+const exportLine = `export PATH="${binDir}:$PATH"`;
+const marker = '# added by relay';
+const block = `\n${exportLine}  ${marker}\n`;
+
+const rcFiles = ['.bashrc', '.zshrc', '.profile'].map(f => join(home, f));
+let patched = false;
+
+for (const rc of rcFiles) {
+  if (!existsSync(rc)) continue;
+  try {
+    if (readFileSync(rc, 'utf8').includes(marker)) continue; // idempotent
+    appendFileSync(rc, block);
+    console.log(`  relay: added ${binDir} to PATH in ~/${require('path').basename(rc)}`);
+    patched = true;
+  } catch (_) {}
+}
+
+// If no shell rc found, create ~/.bashrc as a last resort
+if (!patched) {
+  const bashrc = join(home, '.bashrc');
+  try {
+    appendFileSync(bashrc, block);
+    console.log(`  relay: created ~/.bashrc with PATH entry for ${binDir}`);
+    patched = true;
+  } catch (_) {}
+}
+
+// ── Fish shell ────────────────────────────────────────────────────────────────
+const fishConfig = join(home, '.config', 'fish', 'config.fish');
+const fishMarker = '# added by relay';
+const fishLine = `\nset -gx PATH "${binDir}" $PATH  ${fishMarker}\n`;
+
+if (existsSync(fishConfig)) {
+  try {
+    if (!readFileSync(fishConfig, 'utf8').includes(fishMarker)) {
+      appendFileSync(fishConfig, fishLine);
+      console.log(`  relay: added ${binDir} to PATH in ~/.config/fish/config.fish`);
+      patched = true;
+    }
+  } catch (_) {}
+}
+
+if (patched) {
+  console.log(`  relay: restart your shell (or 'source ~/.bashrc' / 'source ~/.zshrc') then try: relay list`);
+}

package/relay

@@ -12,6 +12,7 @@ RELAY_DIR="${HOME}/.claude-relay"
 CREDS_STORE="${RELAY_DIR}/credentials"
 META_STORE="${RELAY_DIR}/meta"
 CURRENT_FILE="${RELAY_DIR}/current"
+UPDATE_CACHE="${RELAY_DIR}/.update_cache"
 CLAUDE_DIR="${HOME}/.claude"
 CLAUDE_JSON="${HOME}/.claude.json"
 REAL_CLAUDE=$(command -v claude 2>/dev/null || echo "")
@@ -353,6 +354,9 @@ do_switch() {
   local email; email=$(get_meta_email "${name}")
   printf "\n  ${GR}${B}✓ switched → %s${R}  ${D}%s${R}\n" "${name}" "${email}"
   printf "  ${D}Restart claude to apply. Resume last session: ${CY}claude -c${R}\n\n"
+
+  # ponytail: sentinel lets autoswitch daemon skip this account until threshold hit
+  printf '{"account":"%s","ts":%s}' "${name}" "$(date +%s)" > "${RELAY_DIR}/manual_switch"
 }
 
 # ══════════════════════════════════════════════════════════════════
@@ -368,14 +372,21 @@ _sync_current_creds() {
   [[ -n "${live}" ]] && printf '%s' "${live}" > "$(account_creds "${cur}")"
 }
 
-cmd_quick() { _sync_current_creds; render_table quick "${CREDS_STORE}" "${META_STORE}" "$(current_name)" "$@"; }
+cmd_quick() {
+  _check_update_bg
+  _sync_current_creds
+  render_table quick "${CREDS_STORE}" "${META_STORE}" "$(current_name)" "$@"
+  _show_update_notice
+}
 
 cmd_list() {
+  _check_update_bg
   hdr "Account List"
   _sync_current_creds
   render_table full "${CREDS_STORE}" "${META_STORE}" "$(current_name)" "$@"
   echo ""
   ok "Inside Claude Code: ${CY}!relay <index>${R} to switch"
+  _show_update_notice
 }
 
 cmd_status() {
@@ -447,6 +458,8 @@ EOF
   [[ -d "${CLAUDE_DIR}/projects" ]] && \
     n=$(find "${CLAUDE_DIR}/projects" -name "*.jsonl" 2>/dev/null | wc -l | tr -d ' ')
   printf "\n  ${B}Sessions:${R} %s (shared across all accounts in ~/.claude/projects/)\n" "${n}"
+  _check_update_bg
+  _show_update_notice
 }
 
 cmd_add() {
@@ -596,6 +609,8 @@ print()
 print(f'  {total} session(s)' if total else '  No sessions found')
 EOF
   log "${CY}claude -c${R} resume last  ${D}|${R}  ${CY}claude -r${R} pick one  ${D}|${R}  ${CY}claude --resume <id>${R}"
+  _check_update_bg
+  _show_update_notice
 }
 
 cmd_install() {
@@ -648,6 +663,527 @@ cmd_rename() {
   ok "Renamed '${B}${old}${R}' → '${B}${new}${R}'"
 }
 
+AUTOSWITCH_DAEMON="${RELAY_DIR}/autoswitch-daemon.py"
+AUTOSWITCH_PLIST="${HOME}/Library/LaunchAgents/com.relay.autoswitch.plist"
+AUTOSWITCH_SERVICE="${HOME}/.config/systemd/user/relay-autoswitch.service"
+
+_extract_daemon() {
+  cat > "${AUTOSWITCH_DAEMON}" <<'DAEMON_EOF'
+#!/usr/bin/env python3
+"""relay autoswitch daemon — runs in background, switches accounts by usage threshold."""
+import json, os, sys, time, datetime, urllib.request, urllib.error, platform, subprocess, signal
+
+RELAY_DIR    = os.path.expanduser('~/.claude-relay')
+CONFIG_FILE  = os.path.join(RELAY_DIR, 'autoswitch.json')
+LOCK_FILE    = os.path.join(RELAY_DIR, 'autoswitch.lock')
+LOG_FILE     = os.path.join(RELAY_DIR, 'autoswitch.log')
+MANUAL_FILE  = os.path.join(RELAY_DIR, 'manual_switch')
+CURRENT_FILE = os.path.join(RELAY_DIR, 'current')
+CREDS_DIR    = os.path.join(RELAY_DIR, 'credentials')
+CACHE_FILE   = os.path.join(RELAY_DIR, 'usage_cache.json')
+CACHE_TTL    = 120  # seconds — same as render_table
+
+# ── lock ──────────────────────────────────────────────────────────
+def write_lock():
+    with open(LOCK_FILE, 'w') as f: f.write(str(os.getpid()))
+
+def remove_lock():
+    try: os.remove(LOCK_FILE)
+    except: pass
+
+def lock_pid():
+    try: return int(open(LOCK_FILE).read().strip())
+    except: return None
+
+def is_running(pid):
+    try: os.kill(pid, 0); return True
+    except: return False
+
+def check_single_instance():
+    pid = lock_pid()
+    if pid and is_running(pid):
+        print(f'daemon already running (pid {pid})', file=sys.stderr); sys.exit(1)
+    write_lock()
+
+signal.signal(signal.SIGTERM, lambda *_: (remove_lock(), sys.exit(0)))
+
+# ── log ───────────────────────────────────────────────────────────
+def rotate_log():
+    """Keep last 200 lines if log exceeds 500 lines. Called once at startup."""
+    try:
+        lines = open(LOG_FILE).readlines()
+        if len(lines) > 500:
+            with open(LOG_FILE, 'w') as f: f.writelines(lines[-200:])
+    except: pass
+
+def log_event(event, **kwargs):
+    entry = {'ts': int(time.time()), 'event': event, **kwargs}
+    with open(LOG_FILE, 'a') as f: f.write(json.dumps(entry) + '\n')
+
+# ── notify ────────────────────────────────────────────────────────
+def notify(title, msg):
+    try:
+        p = platform.system()
+        if p == 'Darwin':
+            subprocess.run(['osascript', '-e',
+                f'display notification "{msg}" with title "{title}"'],
+                capture_output=True, timeout=3)
+        elif p == 'Linux':
+            subprocess.run(['notify-send', title, msg],
+                capture_output=True, timeout=3)
+        # Windows: called from .ps1 wrapper, not this script
+    except: pass
+
+# ── credentials ───────────────────────────────────────────────────
+def kc_read():
+    p = platform.system()
+    if p == 'Darwin':
+        r = subprocess.run(['security', 'find-generic-password',
+            '-s', 'Claude Code-credentials', '-a', subprocess.run(
+                ['whoami'], capture_output=True, text=True).stdout.strip(), '-w'],
+            capture_output=True, text=True)
+        return r.stdout.strip() if r.returncode == 0 else ''
+    else:
+        live = os.path.join(os.path.expanduser('~'), '.claude', '.credentials.json')
+        try: return open(live).read()
+        except: return ''
+
+def kc_write(content):
+    p = platform.system()
+    if p == 'Darwin':
+        user = subprocess.run(['whoami'], capture_output=True, text=True).stdout.strip()
+        svc = 'Claude Code-credentials'
+        subprocess.run(['security', 'delete-generic-password', '-s', svc, '-a', user], capture_output=True)
+        subprocess.run(['security', 'add-generic-password', '-s', svc, '-a', user, '-w', content], capture_output=True)
+    else:
+        live = os.path.join(os.path.expanduser('~'), '.claude', '.credentials.json')
+        with open(live, 'w') as f: f.write(content)
+        os.chmod(live, 0o600)
+
+def do_switch(name):
+    cred = os.path.join(CREDS_DIR, name + '.json')
+    current = open(CURRENT_FILE).read().strip() if os.path.exists(CURRENT_FILE) else ''
+    if current and os.path.exists(os.path.join(CREDS_DIR, current + '.json')):
+        live = kc_read()
+        if live:
+            with open(os.path.join(CREDS_DIR, current + '.json'), 'w') as f: f.write(live)
+    with open(CURRENT_FILE, 'w') as f: f.write(name)
+    content = open(cred).read()
+    kc_write(content)
+
+# ── usage fetch ───────────────────────────────────────────────────
+def load_cache():
+    try: return json.load(open(CACHE_FILE))
+    except: return {}
+
+def save_cache(c):
+    try:
+        with open(CACHE_FILE, 'w') as f: json.dump(c, f)
+    except: pass
+
+def fetch_usage(name):
+    cred_path = os.path.join(CREDS_DIR, name + '.json')
+    try:
+        d = json.load(open(cred_path))
+        oauth = d.get('claudeAiOauth') or {}
+        tok = oauth.get('accessToken', '')
+        if not tok: return None
+
+        expires_at_ms = oauth.get('expiresAt', 0)
+        now_ms = time.time() * 1000
+        if expires_at_ms and now_ms > expires_at_ms: return 'expired'
+
+        c = load_cache()
+        entry = c.get(name)
+        if entry and time.time() - entry.get('ts', 0) < CACHE_TTL:
+            return entry.get('data')
+
+        req = urllib.request.Request(
+            'https://api.anthropic.com/api/oauth/usage',
+            headers={'Authorization': 'Bearer ' + tok, 'User-Agent': 'relay/2.0'})
+        with urllib.request.urlopen(req, timeout=6) as r:
+            data = json.loads(r.read())
+        c[name] = {'ts': time.time(), 'data': data}
+        save_cache(c)
+        return data
+    except urllib.error.HTTPError as e:
+        return 'expired' if e.code == 401 else None
+    except: return None
+
+def get_utilization(usage_data):
+    """Return 5hr utilization % or None."""
+    if not isinstance(usage_data, dict): return None
+    fh = usage_data.get('five_hour') or {}
+    u = fh.get('utilization')
+    return int(u) if u is not None else None
+
+# ── manual switch protection ───────────────────────────────────────
+def get_manual_switch():
+    try: return json.load(open(MANUAL_FILE))
+    except: return None
+
+def clear_manual_switch():
+    try: os.remove(MANUAL_FILE)
+    except: pass
+
+# ── main loop ─────────────────────────────────────────────────────
+def load_config():
+    try: return json.load(open(CONFIG_FILE))
+    except: return None
+
+def main():
+    check_single_instance()
+    rotate_log()
+    log_event('start')
+
+    while True:
+        cfg = load_config()
+        if not cfg:
+            time.sleep(60); continue
+
+        order = cfg.get('order', [])
+        thresholds = cfg.get('thresholds', {})
+        poll = cfg.get('poll', {})
+        low_min   = int(poll.get('low_minutes', 10))
+        high_min  = int(poll.get('high_minutes', 2))
+        high_thr  = int(poll.get('high_threshold', 50))
+
+        if not order:
+            time.sleep(60); continue
+
+        current = open(CURRENT_FILE).read().strip() if os.path.exists(CURRENT_FILE) else ''
+
+        usage = {name: fetch_usage(name) for name in order}
+
+        cur_util = get_utilization(usage.get(current))
+        sleep_sec = high_min * 60 if (cur_util is not None and cur_util >= high_thr) else low_min * 60
+
+        manual = get_manual_switch()
+        if manual and manual.get('account') == current:
+            threshold = thresholds.get(current)
+            if threshold is not None and cur_util is not None and cur_util >= threshold:
+                clear_manual_switch()
+            else:
+                time.sleep(sleep_sec); continue
+
+        cur_threshold = thresholds.get(current)
+        if cur_threshold is None or cur_util is None or cur_util < cur_threshold:
+            time.sleep(sleep_sec); continue
+
+        candidates = [(n, get_utilization(usage.get(n))) for n in order if n != current]
+        under = [(n, u) for n, u in candidates if u is not None and thresholds.get(n) is not None and u < thresholds[n]]
+
+        if under:
+            target, target_util = under[0]
+        else:
+            measured = [(n, u) for n, u in candidates if u is not None]
+            if not measured:
+                time.sleep(sleep_sec); continue
+            target, target_util = min(measured, key=lambda x: x[1])
+            log_event('all_over_threshold', selected=target, usage=target_util)
+            notify('relay', f'All accounts over threshold — switching to {target} ({target_util}%)')
+            do_switch(target)
+            time.sleep(sleep_sec); continue
+
+        log_event('switch', frm=current, to=target, usage=cur_util)
+        notify('relay', f'switched {current} → {target} ({current} at {cur_util}%)')
+        do_switch(target)
+        time.sleep(sleep_sec)
+
+if __name__ == '__main__':
+    main()
+DAEMON_EOF
+  chmod 755 "${AUTOSWITCH_DAEMON}"
+}
+
+cmd_autoswitch_config() {
+  hdr "autoswitch — configure"
+
+  local accounts=()
+  local name
+  while IFS= read -r name; do accounts+=("${name}"); done < <(list_account_names)
+
+  if [[ ${#accounts[@]} -eq 0 ]]; then
+    err "No accounts found. Run: relay add <name>"
+    exit 1
+  fi
+
+  echo ""
+  printf "  Accounts found: ${CY}%s${R}\n\n" "$(IFS=', '; echo "${accounts[*]}")"
+
+  printf "  ${B}Switch order${R} (comma-separated, only listed accounts join autoswitch):\n"
+  printf "  > "; read -r order_input
+  local order_str; order_str=$(echo "${order_input}" | "${PY}" -c "
+import sys,re
+raw=sys.stdin.read().strip()
+names=[x.strip() for x in raw.split(',') if x.strip()]
+print(','.join(names))")
+
+  echo ""
+  printf "  ${B}Thresholds${R} (press enter to skip account — it won't join autoswitch):\n"
+  local thresholds_json="{"
+  local order_json="["
+  local first_order=1
+  local first_thresh=1
+  IFS=',' read -ra order_arr <<< "${order_str}"
+  for acct in "${order_arr[@]}"; do
+    printf "  %s threshold %% [default 80]: " "${acct}"
+    read -r val
+    if [[ -z "${val}" ]]; then
+      continue
+    fi
+    [[ ${first_order} -eq 0 ]] && order_json+=","
+    order_json+="\"${acct}\""
+    first_order=0
+    [[ ${first_thresh} -eq 0 ]] && thresholds_json+=","
+    thresholds_json+="\"${acct}\":${val}"
+    first_thresh=0
+  done
+  order_json+="]"
+  thresholds_json+="}"
+
+  echo ""
+  printf "  ${B}Poll interval${R} — low usage (minutes) [default 10]: "
+  read -r low_min; low_min="${low_min:-10}"
+  printf "  ${B}Poll interval${R} — high usage (minutes) [default 2]: "
+  read -r high_min; high_min="${high_min:-2}"
+  printf "  ${B}High usage starts at${R} %% [default 50]: "
+  read -r high_thr; high_thr="${high_thr:-50}"
+
+  local cfg_file="${RELAY_DIR}/autoswitch.json"
+  printf '{"order":%s,"thresholds":%s,"poll":{"low_minutes":%s,"high_minutes":%s,"high_threshold":%s}}' \
+    "${order_json}" "${thresholds_json}" "${low_min}" "${high_min}" "${high_thr}" \
+    | "${PY}" -c "import json,sys; print(json.dumps(json.load(sys.stdin), indent=2))" \
+    > "${cfg_file}"
+
+  echo ""
+  ok "Saved to ${cfg_file}"
+  log "Run ${CY}relay autoswitch start${R} to activate"
+}
+
+cmd_autoswitch_start() {
+  [[ -f "${RELAY_DIR}/autoswitch.json" ]] || {
+    err "No config found. Run: relay autoswitch config"
+    exit 1
+  }
+
+  hdr "autoswitch — start"
+  _extract_daemon
+  log "Daemon extracted to ${AUTOSWITCH_DAEMON}"
+
+  local py; py=$(command -v python3 || command -v python || echo "")
+  [[ -z "${py}" ]] && { err "python3 required"; exit 1; }
+
+  if [[ "$(uname)" == "Darwin" ]]; then
+    mkdir -p "${HOME}/Library/LaunchAgents"
+    cat > "${AUTOSWITCH_PLIST}" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key><string>com.relay.autoswitch</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${py}</string>
+        <string>${AUTOSWITCH_DAEMON}</string>
+    </array>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+    <key>StandardOutPath</key><string>${RELAY_DIR}/autoswitch-daemon.log</string>
+    <key>StandardErrorPath</key><string>${RELAY_DIR}/autoswitch-daemon.log</string>
+</dict>
+</plist>
+PLIST
+    launchctl unload "${AUTOSWITCH_PLIST}" 2>/dev/null || true
+    launchctl load "${AUTOSWITCH_PLIST}"
+    ok "Daemon started via launchd"
+
+  elif command -v systemctl >/dev/null 2>&1 && systemctl --user status >/dev/null 2>&1; then
+    mkdir -p "${HOME}/.config/systemd/user"
+    cat > "${AUTOSWITCH_SERVICE}" <<SVCEOF
+[Unit]
+Description=relay autoswitch daemon
+
+[Service]
+ExecStart=${py} ${AUTOSWITCH_DAEMON}
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+SVCEOF
+    systemctl --user daemon-reload
+    systemctl --user enable --now relay-autoswitch
+    ok "Daemon started via systemd"
+
+  else
+    # ponytail: cron fallback — daemon's lock file prevents overlap
+    local cron_entry="*/2 * * * * ${py} ${AUTOSWITCH_DAEMON}"
+    ( crontab -l 2>/dev/null | grep -v "autoswitch-daemon"; echo "${cron_entry}" ) | crontab -
+    ok "Daemon scheduled via cron (every 2 min)"
+    warn "For persistent autoswitch, install systemd or use macOS"
+  fi
+
+  log "Run ${CY}relay autoswitch status${R} to verify"
+}
+
+cmd_autoswitch_stop() {
+  hdr "autoswitch — stop"
+
+  if [[ "$(uname)" == "Darwin" ]] && [[ -f "${AUTOSWITCH_PLIST}" ]]; then
+    launchctl unload "${AUTOSWITCH_PLIST}" 2>/dev/null || true
+    rm -f "${AUTOSWITCH_PLIST}"
+    ok "Removed launchd job"
+
+  elif command -v systemctl >/dev/null 2>&1; then
+    systemctl --user disable --now relay-autoswitch 2>/dev/null || true
+    rm -f "${AUTOSWITCH_SERVICE}"
+    systemctl --user daemon-reload
+    ok "Removed systemd service"
+
+  else
+    crontab -l 2>/dev/null | grep -v "autoswitch-daemon" | crontab -
+    ok "Removed cron entry"
+  fi
+
+  local pid; pid=$(cat "${RELAY_DIR}/autoswitch.lock" 2>/dev/null || echo "")
+  if [[ -n "${pid}" ]]; then
+    kill "${pid}" 2>/dev/null || true
+  fi
+  rm -f "${RELAY_DIR}/autoswitch.lock"
+  ok "Daemon stopped"
+}
+
+cmd_autoswitch_status() {
+  hdr "autoswitch — status"
+
+  local pid; pid=$(cat "${RELAY_DIR}/autoswitch.lock" 2>/dev/null || echo "")
+  if [[ -n "${pid}" ]] && kill -0 "${pid}" 2>/dev/null; then
+    printf "  ${B}Daemon:${R}  ${GR}● running${R}  (pid ${pid})\n"
+  else
+    printf "  ${B}Daemon:${R}  ${D}○ stopped${R}\n"
+  fi
+
+  local cfg="${RELAY_DIR}/autoswitch.json"
+  if [[ ! -f "${cfg}" ]]; then
+    warn "No config. Run: relay autoswitch config"
+    return 0
+  fi
+
+  printf "  ${B}Config:${R}  ${D}%s${R}\n\n" "${cfg}"
+
+  local current; current=$(current_name)
+
+  "${PY}" - "${cfg}" "${current}" <<'EOF'
+import json, sys, os, time
+
+cfg = json.load(open(sys.argv[1]))
+current = sys.argv[2]
+order = cfg.get('order', [])
+thresholds = cfg.get('thresholds', {})
+relay_dir = os.path.expanduser('~/.claude-relay')
+cache_file = os.path.join(relay_dir, 'usage_cache.json')
+
+R='\033[0m'; B='\033[1m'; D='\033[2m'
+GR='\033[32m'; YL='\033[33m'; RD='\033[31m'; CY='\033[36m'
+
+try: cache = json.load(open(cache_file))
+except: cache = {}
+
+def get_util(name):
+    entry = cache.get(name)
+    if not entry: return None
+    data = entry.get('data') if isinstance(entry, dict) else None
+    if not isinstance(data, dict): return None
+    fh = data.get('five_hour') or {}
+    u = fh.get('utilization')
+    return int(u) if u is not None else None
+
+print(f'  {B}{"order":<4} {"account":<14} {"threshold":<12} {"cached usage":<14}{R}')
+print(f'  {D}{"─"*52}{R}')
+for i, name in enumerate(order, 1):
+    cur = name == current
+    marker = f'{GR}●{R}' if cur else ' '
+    ncol = GR + B if cur else B
+    thr = thresholds.get(name)
+    thr_s = f'{thr}%' if thr is not None else f'{D}skipped{R}'
+    util = get_util(name)
+    util_s = f'{util}%' if util is not None else f'{D}—{R}'
+    over = thr is not None and util is not None and util >= thr
+    if over: util_s += f' {YL}⚠ over{R}'
+    next_s = ''
+    if not cur and not over:
+        prev_over = all(
+            (thresholds.get(order[j]) is not None and
+             get_util(order[j]) is not None and
+             get_util(order[j]) >= thresholds[order[j]])
+            for j in range(i-1)
+        )
+        if prev_over: next_s = f' {CY}← next{R}'
+    print(f'  {marker} {D}{i:<2}{R}{ncol}{name:<14}{R} {thr_s:<12} {util_s}{next_s}')
+
+log_file = os.path.join(os.path.dirname(sys.argv[1]), 'autoswitch.log')
+try:
+    lines = open(log_file).readlines()
+    for line in reversed(lines):
+        e = json.loads(line)
+        if e.get('event') == 'switch':
+            print(f'\n  {B}Last switch:{R} {e["frm"]} → {e["to"]}')
+            break
+except: pass
+EOF
+
+  echo ""
+  log "Run ${CY}relay autoswitch log${R} to see full history"
+}
+
+cmd_autoswitch_log() {
+  local log_file="${RELAY_DIR}/autoswitch.log"
+  [[ -f "${log_file}" ]] || { warn "No log yet"; return 0; }
+
+  hdr "autoswitch — log (last 20 events)"
+  "${PY}" - "${log_file}" <<'EOF'
+import json, sys, datetime
+
+R='\033[0m'; B='\033[1m'; D='\033[2m'
+GR='\033[32m'; YL='\033[33m'; RD='\033[31m'; CY='\033[36m'
+
+lines = open(sys.argv[1]).readlines()
+for line in lines[-20:]:
+    try:
+        e = json.loads(line)
+        ts = datetime.datetime.fromtimestamp(e['ts']).strftime('%m/%d %H:%M')
+        ev = e['event']
+        if ev == 'switch':
+            print(f'  {D}{ts}{R}  {GR}switch{R}     {e["frm"]} → {CY}{e["to"]}{R}  ({e.get("usage","?")}%)')
+        elif ev == 'all_over_threshold':
+            print(f'  {D}{ts}{R}  {YL}all_over{R}   → {CY}{e["selected"]}{R}  ({e.get("usage","?")}%) {YL}⚠{R}')
+        elif ev == 'start':
+            print(f'  {D}{ts}{R}  {D}daemon start{R}')
+    except: pass
+EOF
+}
+
+cmd_autoswitch() {
+  local sub="${1:-}"; [[ $# -gt 0 ]] && shift
+  case "${sub}" in
+    config)  cmd_autoswitch_config ;;
+    start)   cmd_autoswitch_start ;;
+    stop)    cmd_autoswitch_stop ;;
+    status)  cmd_autoswitch_status ;;
+    log)     cmd_autoswitch_log ;;
+    *)
+      hdr "autoswitch"
+      printf "  %-32s %s\n" "  relay autoswitch config"  "interactive setup wizard"
+      printf "  %-32s %s\n" "  relay autoswitch start"   "install and start daemon"
+      printf "  %-32s %s\n" "  relay autoswitch stop"    "stop and remove daemon"
+      printf "  %-32s %s\n" "  relay autoswitch status"  "show daemon state + config"
+      printf "  %-32s %s\n" "  relay autoswitch log"     "show recent switch history"
+      echo ""
+      ;;
+  esac
+}
+
 _script_dir() {
   # Resolve symlinks so we find package.json even when installed via npm/symlink
   local src="$0"
@@ -666,6 +1202,68 @@ cmd_version() {
   printf "relay %s\n" "$(_read_version)"
 }
 
+# ── Update notification helpers ───────────────────────────────────────────────
+# Cache format: "<epoch>:<version>"  TTL = 24h
+_check_update_bg() {
+  (
+    local ttl=86400
+    if [[ -f "${UPDATE_CACHE}" ]]; then
+      local cached; cached=$(cat "${UPDATE_CACHE}" 2>/dev/null)
+      local ts="${cached%%:*}"
+      local now; now=$(date +%s)
+      [[ $(( now - ts )) -lt ${ttl} ]] && exit 0
+    fi
+    local ver
+    ver=$("${PY}" - 2>/dev/null <<'PYEOF'
+import urllib.request, json, sys
+def fetch(url, h={}):
+    r = urllib.request.Request(url, headers=h)
+    with urllib.request.urlopen(r, timeout=6) as resp:
+        return json.loads(resp.read())
+try:
+    d = fetch('https://api.github.com/repos/darkstar1227/relay/releases/latest',
+              {'User-Agent': 'relay-update'})
+    print(d['tag_name'].lstrip('v')); sys.exit(0)
+except Exception: pass
+try:
+    d = fetch('https://registry.npmjs.org/@dst-justin%2frelay/latest')
+    print(d['version'])
+except Exception: sys.exit(1)
+PYEOF
+)
+    [[ -n "${ver}" ]] && printf '%s:%s' "$(date +%s)" "${ver}" > "${UPDATE_CACHE}"
+  ) >/dev/null 2>&1 &
+  disown 2>/dev/null || true
+}
+
+_show_update_notice() {
+  local current; current=$(_read_version)
+  local latest=""
+  if [[ -f "${UPDATE_CACHE}" ]]; then
+    local cached; cached=$(cat "${UPDATE_CACHE}" 2>/dev/null)
+    latest="${cached#*:}"
+  fi
+  if [[ -n "${latest}" && "${latest}" != "${current}" ]]; then
+    printf "\n  ${D}relay version: ${B}${current}${R}${D} → ${CY}${B}${latest}${R}${D} available — run ${CY}relay update${R}${D} to install${R}\n"
+  else
+    local ver_display="${latest:-${current}}"
+    printf "\n  ${D}relay version: ${B}${ver_display}${R}${D} (up to date)${R}\n"
+  fi
+}
+
+# Detect how relay was originally installed:
+#   npm    — package.json present in script dir (npm unpacks the full package)
+#   git    — .git dir present in script dir
+#   direct — bare script copy (no package.json, no .git)
+_detect_install_method() {
+  local d; d=$(_script_dir)
+  # .git check first: git clone has both .git AND package.json; npm publish strips .git
+  if [[ -d "${d}/.git" ]];      then echo "git"
+  elif [[ -f "${d}/package.json" ]]; then echo "npm"
+  else                                  echo "direct"
+  fi
+}
+
 cmd_update() {
   hdr "Update relay"
 
@@ -705,18 +1303,43 @@ PYEOF
   fi
 
   local relay_dir; relay_dir=$(_script_dir)
-  local npm_cmd; npm_cmd=$(command -v npm 2>/dev/null)
-  if [[ -n "${npm_cmd}" ]]; then
-    log "Installing via npm..."
-    npm install -g @dst-justin/relay@latest
-    ok "Updated to $(_read_version)"
-  elif [[ -d "${relay_dir}/.git" ]]; then
-    log "npm not found — updating via git..."
-    git -C "${relay_dir}" pull
-  else
-    err "Cannot update: npm not found and no .git directory"
-    log "Install via npm: ${CY}npm install -g @dst-justin/relay@latest${R}"
-  fi
+  local method; method=$(_detect_install_method)
+
+  case "${method}" in
+    npm)
+      local npm_cmd; npm_cmd=$(command -v npm 2>/dev/null)
+      if [[ -n "${npm_cmd}" ]]; then
+        log "Updating via npm (original install method)..."
+        npm install -g @dst-justin/relay@latest
+        ok "Updated to $(_read_version)"
+      else
+        err "npm not found — reinstall npm and retry"
+        log "Or update manually: ${CY}npm install -g @dst-justin/relay@latest${R}"
+      fi ;;
+    git)
+      log "Updating via git pull (original install method)..."
+      git -C "${relay_dir}" pull ;;
+    direct)
+      log "Updating via direct download (original install method)..."
+      local script_path; script_path=$(readlink -f "$0" 2>/dev/null || echo "$0")
+      "${PY}" - "${script_path}" "${latest}" <<'PYEOF'
+import urllib.request, sys, os, stat
+script_path, version = sys.argv[1], sys.argv[2]
+url = f'https://raw.githubusercontent.com/darkstar1227/relay/v{version}/relay'
+try:
+    with urllib.request.urlopen(url, timeout=15) as r:
+        content = r.read()
+    tmp = script_path + '.tmp'
+    with open(tmp, 'wb') as f: f.write(content)
+    os.chmod(tmp, stat.S_IRWXU | stat.S_IRGRP | stat.S_IXGRP | stat.S_IROTH | stat.S_IXOTH)
+    os.replace(tmp, script_path)
+except Exception as e:
+    print(f'  download failed: {e}', file=sys.stderr); sys.exit(1)
+PYEOF
+      ok "Updated ${script_path} to ${latest}" ;;
+  esac
+  # Invalidate update cache so next display shows fresh state
+  rm -f "${UPDATE_CACHE}" 2>/dev/null || true
 }
 
 cmd_uninstall() {
@@ -766,8 +1389,15 @@ cmd_help() {
   printf "  %-32s %s\n" "  relay update"              "update to latest version"
   printf "  %-32s %s\n" "  relay uninstall"          "remove relay and all account data"
   echo ""
+  printf "  ${B}Autoswitch${R}\n"
+  printf "  %-32s %s\n" "  relay autoswitch config"   "set up auto-switching"
+  printf "  %-32s %s\n" "  relay autoswitch start/stop" "manage background daemon"
+  printf "  %-32s %s\n" "  relay autoswitch status"   "daemon state + thresholds"
+  echo ""
   printf "  ${D}switches the OAuth credential (macOS Keychain / Linux ~/.claude/.credentials.json); sessions are shared${R}\n"
   printf "  ${D}after switching: claude -c to resume, claude --resume <id> for a specific session${R}\n\n"
+  _check_update_bg
+  _show_update_notice
 }
 
 # ══════════════════════════════════════════════════════════════════
@@ -798,6 +1428,7 @@ case "${CMD}" in
   remove|rm|del)    cmd_remove "$@" ;;
   rename|mv)        cmd_rename "$@" ;;
   sessions|sess)    cmd_sessions ;;
+  autoswitch|as)    cmd_autoswitch "$@" ;;
   version|--version|-V) cmd_version ;;
   update)           cmd_update ;;
   install)          cmd_install ;;