pan-kill

name	pan-kill
description	pan kill <id> — stop a running agent (workspace and branch preserved)
triggers	["pan kill","stop agent","kill agent","terminate agent","abort agent"]
allowed-tools	["Bash","Read"]

Stop Agent

Overview

This skill guides you through gracefully stopping a running autonomous agent and cleaning up its resources.

When to Use

• Agent is stuck or not making progress
• Need to reassign the work
• Agent completed work and should be stopped
• Emergency stop needed
• Freeing up system resources

Quick Command

# Using pan CLI
pan kill ISSUE-123

# Or directly via tmux
tmux kill-session -t agent-ISSUE-123

Workflow

1. Check Agent Status First

Before killing, understand what the agent is doing:

# List running agents
pan status

# Or via tmux
tmux list-sessions | grep agent

# See recent activity
tmux capture-pane -t agent-ISSUE-123 -p | tail -30

2. Graceful Shutdown (Recommended)

Give the agent a chance to save state:

# Send shutdown message (ALWAYS use pan tell, NOT raw tmux)
pan tell ISSUE-123 "Please save your progress to STATE.md and stop working."

# Wait for acknowledgment
sleep 10
tmux capture-pane -t agent-ISSUE-123 -p | tail -10

# Then kill the session
tmux kill-session -t agent-ISSUE-123

WARNING: DO NOT use raw tmux send-keys - agents often forget the Enter key. Always use pan tell which handles this correctly.

3. Immediate Stop (If Needed)

# Kill immediately
tmux kill-session -t agent-ISSUE-123

4. Verify Stopped

# Confirm session is gone
tmux list-sessions | grep agent-ISSUE-123

# Should return nothing

5. Clean Up (Optional)

# The workspace remains for inspection
ls -la /path/to/workspaces/ISSUE-123/

# View any uncommitted work
cd /path/to/workspaces/ISSUE-123
git status
git diff

Kill All Agents

# Kill all agent sessions
tmux list-sessions -F "#{session_name}" | grep "^agent-" | xargs -I {} tmux kill-session -t {}

# Verify all gone
tmux list-sessions | grep agent

Preserving Work

Before killing, you may want to preserve the agent's progress:

# Attach and review
tmux attach -t agent-ISSUE-123
# Ctrl+b d to detach

# Or capture the full session
tmux capture-pane -t agent-ISSUE-123 -p -S - > agent-output.txt

# Preserve workspace state (per stash-discipline: commit or use salvageable: prefix)
cd /path/to/workspaces/ISSUE-123
git add -A && git commit -m "WIP: state before kill"
# OR, for humans only — explicit salvageable stash:
# git stash push -m "salvageable:ISSUE-123:$(date -u +%Y-%m-%dT%H:%M:%SZ):pre-kill"

After Killing

Options for the work:

1. Resume later - Use pan start ISSUE-123 to spawn a new agent
2. Do it yourself - Work in the existing workspace manually
3. Abandon - Remove the workspace if work is no longer needed

Troubleshooting

Session won't die:

# Force kill with signal
tmux kill-session -t agent-ISSUE-123

# If that fails, find and kill the process
ps aux | grep "agent-ISSUE-123"
kill -9 <PID>

Multiple agents for same issue:

# List all matching sessions
tmux list-sessions | grep ISSUE-123

# Kill each one
tmux kill-session -t agent-ISSUE-123
tmux kill-session -t agent-ISSUE-123-2

Can't find the session:

# List ALL tmux sessions
tmux list-sessions

# Check if process is running outside tmux
ps aux | grep claude

Related Skills

• /pan:status - Check agent status
• /pan:tell - Send message before killing
• /pan:rescue - Recover work from killed agents