pi-stop

ALWAYS stops the current pi.dev coding agent — aborts streaming, kills running tool calls, stops subagents, and reloads your last message for resending.

Three independent stop mechanisms, each covering failure modes of the others:

| # | Mechanism | Scope | When it works | |---|-----------|-------|--------------| | 1 | /stop command | Inside pi | Agent is responsive to keyboard input | | 2 | Ctrl+Shift+X | Inside pi | Agent is streaming, even if thinking/tool-calling | | 3 | pi-stop.sh | Any terminal | Agent is stuck, hung, or in a broken state |

Install

pi install npm:pi-stop

Or from a local checkout:

pi install /path/to/pi-stop

Usage

Inside pi — /stop command

Type /stop and press Enter anytime — even while the agent is mid-response:

/stop

What happens:

1. ctx.abort() fires immediately — stops streaming, tool calls, subagents
2. Waits up to 15 seconds for the agent to fully settle
3. If the agent doesn't stop in time, escalates to SIGINT → SIGTERM → SIGKILL
4. Your last user message is loaded into the editor for editing and resending

Inside pi — Ctrl+Shift+X shortcut

Press Ctrl+Shift+X at any time — same as /stop but faster, works even while the agent is streaming mid-thought.

Can be customised in ~/.pi/agent/keybindings.json:

{
  "Ctrl+Shift+Z": "stop"
}

Outside pi — pi-stop.sh

When pi itself is frozen, hung, or unresponsive:

./pi-stop.sh           # graceful stop
./pi-stop.sh -f        # force kill (skip SIGINT)
./pi-stop.sh -d        # verbose debug output

This script:

1. Finds all pi-coding-agent processes via pgrep
2. Sends SIGINT (graceful abort, skip with -f)
3. Waits 3 seconds, then SIGTERM if alive
4. Waits 2 seconds, then SIGKILL if still alive
5. Also kills orphan child shell processes (bash/sh/zsh)

How it ALWAYS stops

The escalation chain guarantees termination:

ctx.abort()  →  ctx.waitForIdle()  →  SIGINT  →  SIGTERM  →  SIGKILL
   (API)           (15s timeout)      (3s)       (2s)      (nuclear)

Each layer covers the failure modes of the layer above it:

• abort() fails if the abort signal is already consumed or the agent is in a bad state
• waitForIdle() hangs if the agent never emits agent_end (e.g., subagent stuck in a loop)
• SIGINT is ignored if the process is in an uninterruptible sleep
• SIGTERM is caught but ignored by some misbehaving processes
• SIGKILL cannot be caught or ignored — always terminates

File layout

pi-stop/
├── extensions/
│   └── stop.ts        # Pi extension: /stop command + Ctrl+Shift+X shortcut
├── test/
│   └── stop.test.ts   # Tests for the extension
├── pi-stop.sh          # Standalone kill script (works outside pi)
├── package.json
└── README.md

License

MIT