kill-switch

Emergency stop for shared Claude Code accounts.

The problem

You and a friend share a Claude Max account. One person's heavy session burns through the 5-hour rate limit window, and the other person gets throttled mid-work with no warning. There's no built-in way to set per-person budgets, no way to remotely stop someone's sessions, and no way to know who used what.

What this does

kill-switch sits between Claude Code and your shared account. It monitors credit usage (via cc-retrospect and cc-budget), enforces per-user limits, and kills sessions when thresholds are crossed. Any shared user can trigger it remotely — from WhatsApp, a curl command, or anywhere with HTTP access.

When the kill switch fires, three things happen simultaneously:

1. All active Claude sessions receive SIGTERM (graceful shutdown preserving cc-retrospect cost data)
2. All cc-later background agents are killed and dispatch is paused
3. A state file is written that the Claude Code hook reads — every future prompt is blocked until resume

How it integrates

kill-switch doesn't work alone. It's the actuator in a system of four tools:

cc-retrospect ──── tracks cost, fires budget alerts ────┐
                                                         ▼
cc-budget ──────── tracks 5h/7d rate limit % ──────► kill-switch ──── kills sessions
                                                         │              writes state.json
cc-later ◄──────── DISPATCH_ENABLED=false ◄──────────────┤              blocks prompts
                   in-flight agents killed                │
                                                         │
cc-manager ─────── ccm install kill-switch ──────────────►│  (wires hooks)

cc-retrospect computes today_cost on every session stop. When daily spend crosses a budget tier ($75 warning, $200 critical, $400 severe), it fires SCRIPTS__ON_BUDGET_ALERT — which calls kill_switch.py kill. This is one of two trigger paths.

launchd is the other. A plist runs kill_switch.py check every 30 seconds, outside Claude entirely. It reads ~/.claude/cc-budget/state.json for the 5-hour rate limit percentage and ~/.cc-retrospect/state.json for daily cost. If either exceeds the per-user limit in config, it fires the kill sequence. This catches runaway sessions that cc-retrospect wouldn't see until they end.

cc-later dispatches background agents near the end of the 5-hour window. When kill-switch fires, it flips DISPATCH_ENABLED=false in cc-later's config and kills any in-flight agent PIDs from ~/.cc-later/state.json. On resume, dispatch is re-enabled.

cc-manager has kill-switch in its tool registry. ccm install kill-switch wires the prompt-blocking hook into ~/.claude/settings.json for UserPromptSubmit and PreToolUse events.

One file, zero dependencies

kill_switch.py              — CLI + HTTP server + check + all integrations (stdlib only)
hooks/kill-switch-hook.sh   — Claude Code hook (reads state.json, blocks prompts)
relay/relay.py              — cloud relay for Fly.io (WhatsApp + generic webhook)

No pip install. No venv. python3 kill_switch.py status works on any Mac with Python 3.11+.

Quick start

# 1. See current state
python3 kill_switch.py status

# 2. Configure limits
cat > ~/.kill-switch/config.json << 'EOF'
{
  "users": {
    "srinivasvaddi": {"threshold_pct": 50, "daily_cost_limit": 200, "override_token": "s-secret", "resume_minutes": 60},
    "friend":        {"threshold_pct": 40, "daily_cost_limit": 100, "override_token": "f-secret", "resume_minutes": 30}
  },
  "server_port": 9876,
  "server_secret": "shared-key",
  "notify": true
}
EOF

# 3. Install launchd (check every 30s + HTTP server)
python3 kill_switch.py install-launchd

# 4. Install Claude Code hooks
#    ccm install kill-switch
#    or manually: see docs/hooks.md

Commands

Command	What it does
status	State, cost, 5h window %, sessions, cc-later agents, per-project spend
check	Evaluate thresholds, kill if breached, auto-resume if clear (launchd runs this)
kill	Force kill all sessions regardless of thresholds
resume	Lift block, re-enable cc-later dispatch
override --token T -d 30	Bypass kill switch for 30 minutes with auth token
logs [-n 50] [--type kill]	Tail ~/.kill-switch/log.jsonl
serve --port 9876 --secret KEY	HTTP server for relay/webhook calls
install-launchd [--interval 30]	Generate and load launchd plists

Documentation

Doc	Contents
How it works	Kill sequence, hook mechanism, auto-resume logic
Configuration	All config keys, per-user limits, defaults
Integrations	cc-retrospect, cc-later, cc-manager, cc-budget wiring
Remote access	Relay deploy, Tailscale, WhatsApp setup
Hooks	Claude Code hook install, how blocking works
Launchd	macOS service setup, logs, troubleshooting