Skip to main content

Session Recovery Guide

Detect, export, and recover hung or unresponsive Claude Code sessions with zero data loss.

Target Audience: All CODITECT users Last Updated: February 5, 2026 Status: Production Ready

Table of Contents​

  1. When You Need This
  2. Quick Start
  3. Understanding Session States
  4. Recovery Workflows
  5. The /session-rescue Command
  6. Manual Recovery
  7. Prevention
  8. Troubleshooting

When You Need This​

Use session recovery when:

  • A Claude Code session is hung (not responding to input)
  • A session ran out of context and you need to preserve the work
  • You have multiple terminal tabs with Claude running and need to clean up
  • A session was interrupted (crash, power loss, network issue)
  • You want to export and resume a session later

Quick Start​

# Interactive recovery - detects all sessions and lets you choose
/session-rescue

# Auto-export all active sessions (safest option)
/session-rescue --export

# Show status without taking action
/session-rescue --status

# Get resume commands for all sessions
/session-rescue --resume

Understanding Session States​

StateDescriptionIndicator
CURRENTYour active sessionTTY matches your terminal
ACTIVERunning in another terminalProcess exists, recent file activity
HUNGUnresponsiveProcess exists, no file activity > 10 min
ORPHANEDNo process, data remainsSession file exists, no matching PID
COMPLETEDNormally endedSession file archived

How Sessions Are Detected​

The recovery system uses three signals:

  1. Process detection - ps aux finds Claude Code processes
  2. TTY mapping - Each process is mapped to its terminal
  3. File activity - Session JSONL files are checked for recent writes

Recovery Workflows​

Workflow 1: Hung Session (Most Common)​

Your Claude session stopped responding, and you need to recover the work.

Step 1: Open a NEW terminal tab/window
Step 2: Run /session-rescue
Step 3: Select "Export" for the hung session
Step 4: Select "Kill" for the hung session
Step 5: Run /cx to process the exported session
Step 6: Resume with: claude --resume <uuid>

Workflow 2: Context Exhaustion​

Claude ran out of context, and the conversation was summarized or ended.

Step 1: In a new session, run /session-rescue --export
Step 2: Run /cx to extract and index the session
Step 3: In the new session, run /cxq --recent 20 to recall work
Step 4: Continue working with the recovered context

Workflow 3: Multiple Stale Sessions​

You have several terminals with Claude sessions you want to clean up.

Step 1: Run /session-rescue --status (review what's running)
Step 2: Run /session-rescue --export (export all sessions)
Step 3: Run /session-rescue (interactive - kill the ones you don't need)
Step 4: Run /cx to process all exports

Workflow 4: Resume an Old Session​

You want to continue a previous Claude session.

Step 1: Run /session-rescue --resume
Step 2: Copy the desired resume command
Step 3: Run: claude --resume <session-uuid>

The /session-rescue Command​

Interactive Mode (Default)​

/session-rescue

Detects all Claude processes, maps them to terminals, identifies session files, and presents an interactive menu:

CLAUDE SESSIONS DETECTED
┌──────────────────────────────────────────────────┐
│ 1. s013 (PID 3354) - 01e5af14... (56MB)         │
│    Last activity: 35 min ago (HUNG)              │
│ 2. s008 (PID 12308) - 4754dabe... (28MB)        │
│    Last activity: 2 min ago (ACTIVE)             │
│ 3. s009 (PID 9024) - 6df9344a... (39KB)         │
│    Last activity: NOW (CURRENT)                  │
└──────────────────────────────────────────────────┘

For each session, you can:

  • Export - LOSSLESS copy to the pending directory
  • Kill - Terminate the process (with confirmation)
  • Resume - Get the claude --resume command
  • Skip - Take no action

Auto-Export Mode​

/session-rescue --export

Exports ALL active sessions without prompting. This is the safest option when you just want to preserve everything.

Kill Mode​

/session-rescue --kill s013

Kills the Claude process running on a specific TTY. Always exports before killing.

Safety: The current session (your terminal) is protected from self-kill.

Resume Mode​

/session-rescue --resume

Lists all sessions with their resume commands:

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

Status Mode​

/session-rescue --status

Shows all Claude processes and their states without taking any action.

Manual Recovery​

If /session-rescue is not available or you need to recover manually:

Step 1: Find Claude Processes​

ps aux | grep 'claude' | grep -v grep

Step 2: Find Session Files​

# List recent session files (newest first)
ls -lt ~/.claude/projects/*/*.jsonl | head -10

Step 3: Export (LOSSLESS)​

TIMESTAMP=$(date -u '+%Y-%m-%dT%H-%M-%SZ')
SESSION_FILE=~/.claude/projects/<hash>/<uuid>.jsonl

# Copy the file (preserves all data)
cp "$SESSION_FILE" \
   ~/PROJECTS/.coditect-data/sessions-export-pending-anthropic/${TIMESTAMP}-LOSSLESS-session.jsonl

# Verify the copy
md5 "$SESSION_FILE"
md5 ~/PROJECTS/.coditect-data/sessions-export-pending-anthropic/${TIMESTAMP}-LOSSLESS-session.jsonl

Step 4: Kill Hung Process​

# Graceful kill
kill <PID>

# Force kill (if graceful doesn't work after 10 seconds)
kill -9 <PID>

Step 5: Process with /cx​

/cx
# Or manually:
source ~/.coditect/.venv/bin/activate
python3 ~/.coditect/scripts/context-extractor.py

Prevention​

Enable the Context Watcher​

The context watcher auto-exports sessions when they approach context limits:

# Check if running
~/.coditect/bin/coditect-context-watch --status

# Start if not running
launchctl load ~/Library/LaunchAgents/ai.coditect.context-watcher.plist

Regular Exports​

Export your session regularly during long work sessions:

/export                    # Quick export
/sx --llm claude           # Full LOSSLESS export

Monitor Session Size​

Large sessions (>50MB) are more prone to issues. If your session file is growing large:

ls -lh ~/.claude/projects/*/*.jsonl | sort -k5 -h -r | head -5

Consider starting a new session and using /cx + /cxq to carry context forward.

Troubleshooting​

"No Claude processes found"​

This is normal if no Claude sessions are running. Check that you haven't already closed them.

Export Directory Doesn't Exist​

mkdir -p ~/PROJECTS/.coditect-data/sessions-export-pending-anthropic/

Session File Not Found​

Session files are stored in ~/.claude/projects/<hash>/. The hash is derived from your project directory. If the file is missing, the session was likely already archived.

Kill Command Refused​

The system protects your current terminal session. If you need to kill the session you're currently in, open a new terminal first.

MD5 Mismatch After Export​

If the checksums don't match, the export may have been corrupted. Re-run the copy:

cp -f "$SESSION_FILE" "$DEST"

Process Won't Die​

Some hung processes resist graceful kill. Wait 10 seconds then use force:

kill <PID>
sleep 10
kill -9 <PID>
DocumentPurpose
Memory Management Guide/cx, /cxq commands
/session-rescue CommandCommand reference
Session Recovery SkillSkill patterns
/sx CommandMulti-LLM session export
Context WatcherAuto-export service

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