session-health git:20260522.817c2c7A

Immutable. This exact content is served forever at /api/v1/blob/2af4b05f2067e0c5.

---
name: session-health
description: Detect and clean up stuck or corrupted Claude Code sessions. Use when agents crash with stack overflow, when sessions seem stuck, or for routine maintenance. Triggers on "session health", "check sessions", "stuck agent", "agent crashed", "stack overflow", "cleanup sessions".
---

# Session Health Monitor

Detect and clean up problematic Claude Code sessions that can cause crashes.

## Common Issues Detected

| Issue | Symptom | Cause |
|-------|---------|-------|
| **Warmup Loop** | Agent retries same command forever | Sidechain stuck returning "Warmup" errors |
| **Context Explosion** | Stack overflow crash | Too many messages accumulated |
| **Infinite Retry** | Same tool called 50+ times | Tool consistently failing |

## Quick Check

```bash
python ~/.claude/skills/session-health/scripts/check_sessions.py
```

## Auto-Fix Critical Issues

```bash
python ~/.claude/skills/session-health/scripts/check_sessions.py --fix
```

## Check Specific Workspace

```bash
# Replace with your actual project path
python ~/.claude/skills/session-health/scripts/check_sessions.py \
  --path ~/.claude/projects/-home-user-projects-myproject-workspaces-feature-proj-123
```

## Manual Cleanup Steps

If auto-fix doesn't work:

1. **Kill the agent session**:
   ```bash
   tmux kill-session -t agent-proj-123
   ```

2. **Remove session files** (use Python to bypass damage-control):
   ```python
   import os, glob
   # Replace with your actual project path
   path = '~/.claude/projects/-home-user-projects-myproject-workspaces-feature-proj-123/'
   for f in glob.glob(os.path.expanduser(path + '*.jsonl')):
       os.remove(f)
       print(f'Removed: {f}')
   ```

3. **Restart the agent fresh**:
   ```bash
   pan start PROJ-123
   ```

## Thresholds

| Metric | Warning | Critical |
|--------|---------|----------|
| Message count | >500 | >1000 |
| Warmup errors | >10 | >50 |
| File size | >2MB | >5MB |
| Repeated command | >50x | >100x |

## Proactive Monitoring

Add to cron for daily checks:
```bash
0 6 * * * python ~/.claude/skills/session-health/scripts/check_sessions.py --json >> ~/.claude/session-health.log
```