ai-agent-kill-switch - SKILL.md Agent Skill

name: ai-agent-kill-switch description: Phrase-triggered emergency stop system for AI agents. Instantly halts all agent automation when a trigger phrase is detected in session logs, or via manual flag. Use when setting up a safety kill switch, emergency stop, or pause-all-automation mechanism for autonomous agents. Survives restarts via LaunchAgent watchdog. metadata: emoji: 🛑 category: safety platform: macOS, Linux

AI Agent Kill Switch

Hard stop for autonomous agents. Trigger phrase or manual flag → all outbound halts. Designed to be impossible to accidentally bypass.

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│ Trigger     │ ──▶ │ Flag file    │ ──▶ │ Any agent   │
│ (phrase or  │     │ (sentinel)   │     │ script bails│
│ manual)     │     │              │     │ on source   │
└─────────────┘     └──────────────┘     └─────────────┘
       │
       ▼
┌──────────────────┐
│ Watchdog scans   │
│ session JSONL    │  ← LaunchAgent, cron, or fswatch
│ for armed phrase │
└──────────────────┘

Components

Script	Role
`scripts/kill_switch.sh`	Activate the kill switch (creates flag, pauses gateway)
`scripts/kill_switch_watchdog.sh`	Scans session logs for the armed phrase
`scripts/kill_switch_trigger.sh`	Runs when flag appears (notifications, gateway pause)
`scripts/check_flag.sh`	Source this at top of any agent script to auto-abort

Quick Start

1. Activate manually

bash scripts/kill_switch.sh

2. Clear the flag

rm "${KILL_SWITCH_STATE_DIR:-$HOME/.ai-kill-switch}/kill_switch.flag"

3. Protect any script

At the top of any script that makes outbound calls:

#!/usr/bin/env bash
source /path/to/ai-agent-kill-switch/scripts/check_flag.sh
# ... your code runs only if flag absent

Phrase-Based Trigger (watchdog)

The watchdog scans agent session JSONL files for an exact armed phrase. When detected, it creates the sentinel flag.

export ARMED_PHRASE="KILL: AGENT STOP NOW"
export SESSIONS_DIR="$HOME/.openclaw/agents/main/sessions"
bash scripts/kill_switch_watchdog.sh

Run via cron every minute:

* * * * * /path/to/scripts/kill_switch_watchdog.sh >> /tmp/watchdog.log 2>&1

Or via launchd (macOS) — create ~/Library/LaunchAgents/ai.kill-switch.watchdog.plist with StartInterval=60.

Configuration (env vars)

Variable	Default	Purpose
`KILL_SWITCH_STATE_DIR`	`$HOME/.ai-kill-switch`	Where flag/log/state live
`KILL_SWITCH_LOGGER_PATTERN`	(none)	`pkill -f` pattern to terminate on trigger
`ARMED_PHRASE`	`KILL: AGENT STOP NOW`	Watchdog trigger phrase
`SESSIONS_DIR`	`$HOME/.openclaw/agents/main/sessions`	JSONL logs to scan
`NOTIFY_TARGET`	(empty)	Phone/JID to alert on trigger
`NOTIFY_CHANNEL`	`whatsapp`	Notification channel

Why Phrase-Based?

Typing a short kill phrase anywhere the agent is listening (WhatsApp, Twitch chat, a shell session) instantly halts it. No UI, no password, no latency. Designed for the moment you realize something is wrong and you want it stopped now.

Choose an armed phrase that:

Is unlikely to appear naturally in conversation
Contains a distinctive marker like KILL: or STOP-NOW:
You can type reliably under stress

Full Setup

See references/setup.md (if present) for LaunchAgent plist and recovery procedures.