Skip to main content

/session-rescue - Hung Session Recovery

Detect, export, and recover hung Claude terminal sessions with automated process identification and LOSSLESS session backup.

System Prompt​

EXECUTION DIRECTIVE: When the user invokes /session-rescue, you MUST:

  1. Detect all Claude processes via ps aux | grep claude
  2. Map PIDs to TTYs to identify which terminal each session runs in
  3. Identify session UUIDs by parsing ~/.claude/projects/*/*.jsonl
  4. Detect hung sessions (no activity > 10 min but CPU > 0)
  5. Present interactive selection using AskUserQuestion
  6. Execute selected actions (export, kill, resume commands)
  7. Update session log with recovery details

Usage​

/session-rescue                    # Interactive mode: detect and select
/session-rescue --export           # Auto-export all active sessions
/session-rescue --kill <tty>       # Kill specific terminal session (e.g., s013)
/session-rescue --resume           # List sessions available to resume
/session-rescue --status           # Show all Claude processes without action

Options​

OptionDescription
(none)Interactive mode - detect sessions and prompt for action
--exportAutomatically export all active sessions to pending directory
--kill <tty>Kill Claude process on specified TTY (requires confirmation)
--resumeShow all sessions with resume commands
--statusDisplay current session status without taking action
--forceSkip confirmation for kill operations (use with caution)

Workflow​

Step 1: Process Detection​

# Detect Claude processes
ps aux | grep claude | grep -v grep

# Map to TTY
ps aux | grep claude | awk '{print $2, $7, $10, $11}'
# Output: PID TTY CPU COMMAND

Step 2: Session Identification​

# List recent session files
ls -lt ~/.claude/projects/*/*.jsonl | head -15

# Extract session metadata from JSONL
tail -5 <session.jsonl> | python3 -c "import sys,json; ..."

Step 3: Hung Detection​

A session is considered "hung" when:

  • Process exists (PID in ps aux)
  • Session file has no updates > 10 minutes
  • CPU time is still accumulating (process not idle)

Step 4: Interactive Selection​

Present options via AskUserQuestion:

  • Export - LOSSLESS copy to pending directory
  • Kill - Terminate process (with confirmation)
  • Resume - Generate resume command
  • Skip - No action for this session

Step 5: Execute Actions​

Export (LOSSLESS):

TIMESTAMP=$(date -u '+%Y-%m-%dT%H-%M-%SZ')
cp ~/.claude/projects/<hash>/<uuid>.jsonl \
   ~/PROJECTS/.coditect-data/sessions-export-pending-anthropic/${TIMESTAMP}-LOSSLESS-<uuid>.jsonl

Kill (with confirmation):

kill <PID>       # Graceful
kill -9 <PID>    # Force (if --force or user confirms)

Resume:

claude --resume <session-uuid>

Step 6: Session Log Update​

Automatically append entry to session log:

### YYYY-MM-DDTHH:MM:SSZ - [ADMIN] Session Rescue

**Sessions Recovered:**
| UUID | Size | Action | Result |
|------|------|--------|--------|
| abc123... | 56MB | Exported | ✅ |
| def456... | 28MB | Killed | ✅ |

Examples​

Interactive Recovery​

/session-rescue
# Output:
# ┌─────────────────────────────────────────────┐
# │ CLAUDE SESSIONS DETECTED                     │
# ├─────────────────────────────────────────────┤
# │ 1. s013 (PID 3354) - 01e5af14... (56MB)     │
# │    Last activity: 02:30 (HUNG)              │
# │ 2. s008 (PID 12308) - 4754dabe... (28MB)    │
# │    Last activity: 02:16 (HUNG)              │
# │ 3. s009 (PID 9024) - 6df9344a... (39KB)     │
# │    Last activity: NOW (CURRENT)             │
# └─────────────────────────────────────────────┘
# ? Select action for s013 session:
#   > Export to pending
#     Kill process
#     Skip

Auto-Export All​

/session-rescue --export
# Exports all active sessions without prompting

Kill Specific Session​

/session-rescue --kill s013
# Confirmation prompt:
# Kill Claude process PID 3354 on TTY s013? [y/N]

Show Resume Commands​

/session-rescue --resume
# Output:
# Resume commands for available sessions:
# claude --resume 01e5af14-9422-4986-8749-e00802273d54
# claude --resume 4754dabe-4426-4290-ba6d-bed314946d79

Script Reference​

Core Script: scripts/session-recovery.py

class SessionRecovery:
    def detect_claude_processes(self) -> List[ProcessInfo]
    def map_tty_to_session(self, tty: str) -> Optional[SessionInfo]
    def detect_hung_sessions(self, timeout_minutes: int = 10) -> List[SessionInfo]
    def export_session(self, session: SessionInfo, lossless: bool = True) -> Path
    def kill_process(self, pid: int, force: bool = False) -> bool
    def generate_resume_command(self, session: SessionInfo) -> str

Success Output​

✅ COMMAND COMPLETE: /session-rescue
Sessions detected: 3
Sessions exported: 2
Sessions killed: 0
Session log updated: SESSION-LOG-2026-02-05.md

Resume commands:
  claude --resume 01e5af14-9422-4986-8749-e00802273d54
  claude --resume 4754dabe-4426-4290-ba6d-bed314946d79

Completion Checklist​

Before marking complete:

  • All Claude processes detected
  • Session UUIDs identified
  • Hung sessions flagged
  • Selected actions executed
  • Session log updated
  • Resume commands provided

Failure Indicators​

This command has FAILED if:

  • ❌ No Claude processes found (not an error, just info)
  • ❌ Session file parsing failed
  • ❌ Export destination not writable
  • ❌ Kill command failed
  • ❌ Session log update failed

When NOT to Use​

Do NOT use when:

  • No hung sessions exist
  • You want to restart Terminal (just close the app)
  • Session was already exported by context watcher

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Kill without exportLose session dataAlways export first
Force kill currentKills own session--force excludes current TTY
Skip session logLost audit trailAlways update log

Principles​

This command embodies:

  • #3 Complete Execution - Detect → Export → Kill → Resume → Log
  • #8 No Assumptions - Confirm before destructive actions
  • #9 Based on Facts - Uses ps, ls -lt, file metadata

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Version: 1.0.0 Created: 2026-02-05 Author: Claude (Opus 4.5) Track: J.26