agent-kill-switch

Universal emergency stop for running AI agents with state capture and git rollback.

No direct competitor exists — current approaches rely on max_iterations limits or manual process killing. This package provides a structured, cross-platform way to monitor, terminate, and roll back agent processes.

Install

npm install agent-kill-switch

CLI Usage

# Watch an agent process
agent-kill-switch watch 12345 --cwd /my/project

# Kill it with rollback
agent-kill-switch kill 12345 --rollback --reason "burning tokens"

# Kill all watched processes
agent-kill-switch kill all

# Show status of watched processes
agent-kill-switch status

# Dry run — see what would happen
agent-kill-switch kill 12345 --dry-run

Programmatic API

import { KillSwitch } from 'agent-kill-switch';

const ks = new KillSwitch();

// Watch a process
ks.watch(process.pid, { cwd: '/my/project' });

// Check status
const entries = ks.status();
console.log(entries);

// Kill with rollback (from another process or signal handler)
const results = await ks.kill(pid, {
  rollback: true,
  reason: 'runaway agent',
});

// Kill all watched processes
await ks.kill('all');

// Dry run
await ks.kill(pid, { dryRun: true });

// Clean up watchers in current process
ks.stopAll();

Features

• Graceful termination: SIGTERM → 3s → SIGINT → 2s → SIGKILL (Unix) / taskkill → taskkill /F (Windows)
• File tracking: Monitors files modified via fs.watch during agent execution
• Git rollback: --rollback flag stashes uncommitted changes made during the agent session
• State snapshots: Captures process state (PID, duration, files modified, memory) before killing
• CoC integration: Writes EMERGENCY_STOP entries to Chain of Consciousness if @absupport/coc-writer is installed
• Cross-platform: Windows, macOS, Linux
• Zero runtime dependencies

State Snapshot Format

When a process is killed, a snapshot is captured:

{
  "type": "EMERGENCY_STOP",
  "pid": 12345,
  "reason": "burning tokens",
  "files_modified": ["src/index.ts", "src/utils.ts"],
  "duration_seconds": 342,
  "rollback_applied": true,
  "timestamp": "2026-04-22T15:30:00.000Z",
  "memory_usage_mb": 256
}

Configuration

State is stored in $TMPDIR/agent-kill-switch/state.json. Override with the AGENT_KILL_SWITCH_STATE_DIR environment variable.

License

Apache-2.0 — see LICENSE.