Session Cleanup Protocol
Contents
Cleanup Steps
Step 0: Check Permissions (ONE-TIME SETUP)
Purpose: Verify session-cleanup permissions are configured to prevent repeated permission prompts.
Run the permission check script:
"${SKILL_BASE:-$HOME/.claude/skills/session-cleanup}/scripts/check_permissions.sh" "${PROJECT_ROOT:-$PWD}"
Script behavior:
- All permissions present: Exits silently (code 0) → proceed to Step 0.5
- Permissions missing: Exits with details (code 1) → offer configuration
- No settings file: Exits with MISSING_FILE marker → offer to create
When configuration needed:
Present configuration offer to user:
🔧 Session-cleanup skill needs one-time permission setup
Missing required permissions:
- Skill(session-cleanup)
- [Other patterns from script output]
I can configure these automatically. May I update .claude/settings.local.json?
After user approval, execute inline configuration script:
#!/bin/bash
# Inline permission configuration for session-cleanup skill
PROJECT_DIR="${PROJECT_ROOT:-$PWD}"
SETTINGS_FILE="$PROJECT_DIR/.claude/settings.local.json"
mkdir -p "$PROJECT_DIR/.claude"
# Session-cleanup required permission patterns
REQUIRED_PATTERNS='[
"Skill(session-cleanup)",
"Bash(\"${SKILL_BASE:-$HOME/.claude/skills/session-cleanup}/scripts/check_permissions.sh\" \"${PROJECT_ROOT:-$PWD}\")",
"Bash(\"${SKILL_BASE:-$HOME/.claude/skills/session-cleanup}/scripts/check_uncommitted_changes.sh\" \"${PROJECT_ROOT:-$PWD}\")",
"Bash(\"${SKILL_BASE:-$HOME/.claude/skills/session-cleanup}/scripts/detect_complexity.sh\" \"${PROJECT_ROOT:-$PWD}\")",
"Bash(\"${SKILL_BASE:-$HOME/.claude/skills/session-cleanup}/scripts/find_local_cleanup.sh\" \"${PROJECT_ROOT:-$PWD}\")",
"Bash(\"${SKILL_BASE:-$HOME/.claude/skills/session-cleanup}/scripts/check_stale_planning.sh\" \"${PROJECT_ROOT:-$PWD}\")",
"Read(~/.claude/skills/session-cleanup/**)"
]'
if [ ! -f "$SETTINGS_FILE" ]; then
cat > "$SETTINGS_FILE" <<EOF
{
"permissions": {
"allow": $REQUIRED_PATTERNS,
"deny": [],
"ask": []
}
}
EOF
echo "✅ Created $SETTINGS_FILE with session-cleanup permissions"
else
if command -v jq >/dev/null 2>&1; then
REQUIRED_JSON=$(echo "$REQUIRED_PATTERNS" | jq -c '.')
jq --argjson new "$REQUIRED_JSON" \
'.permissions.allow = ([.permissions.allow[], $new[]] | unique)' \
"$SETTINGS_FILE" > "$SETTINGS_FILE.tmp" && mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
echo "✅ Updated $SETTINGS_FILE with session-cleanup permissions"
else
echo "⚠️ jq not found - add these patterns manually to permissions.allow:"
echo "$REQUIRED_PATTERNS"
fi
fi
After configuration: Proceed to Step 0.5. Future sessions will skip this step.
Step 0.5: Check Uncommitted Changes
Ensure clean git state before audit:
"${SKILL_BASE:-$HOME/.claude/skills/session-cleanup}/scripts/check_uncommitted_changes.sh" "${PROJECT_ROOT:-$PWD}"
Script behavior:
- Not a git repo: Exits silently (code 0) → proceed to Step 1
- No uncommitted changes: Exits silently (code 0) → proceed to Step 1
- Uncommitted changes detected: BLOCKS with details (exit code 1)
When blocked: Commit changes first, then re-run "session cleanup".
Step 1: Detect Session Complexity
Determine appropriate depth for session review:
"${SKILL_BASE:-$HOME/.claude/skills/session-cleanup}/scripts/detect_complexity.sh" "${PROJECT_ROOT:-$PWD}"
Output determines depth:
- light: 0-1 commits, <5 files → abbreviated review
- standard: 2-5 commits, 5-15 files → full review
- thorough: 6+ commits, 15+ files → deep review with extra validation
Use the detected depth to calibrate Step 2 analysis.
Step 1.5: Check Stale Planning Docs
Detect planning documents that may be abandoned or need completion:
"${SKILL_BASE:-$HOME/.claude/skills/session-cleanup}/scripts/check_stale_planning.sh" "${PROJECT_ROOT:-$PWD}"
Script behavior:
- No planning directory: Exits silently (code 0) → proceed to Step 2
- No stale docs: Reports active docs (informational) → proceed to Step 2
- Stale docs found (>30 days): Warns with options (code 1) → add to [ASK user] list
When stale docs found:
The script identifies documents that haven't been updated in >30 days and suggests:
- COMPLETE: Integrate findings into permanent docs, then delete
- UPDATE: If work is ongoing, touch file to reset timer
- ABANDON: If obsolete, delete with commit noting abandonment
Add stale docs to the [ASK user] category in Step 2 - user decides disposition.
Why this matters: Planning docs are ephemeral by design. Stale docs indicate either:
- Abandoned work (should be deleted)
- Forgotten integration (should be completed)
- Ongoing work that needs attention (should be updated)
See: CORE_PROCESSES.md § Transient Artifacts Overview for staleness thresholds.
Step 2: Structured Ultrathink
Core of session-cleanup: Guided but flexible analysis.
Execute this ultrathink prompt, adjusting depth based on Step 1:
Ultrathink session review [DEPTH from Step 1]:
Consider these categories:
(a) Session continuity - did work match the plan/resume?
(b) Document staleness - any planning docs ready for deletion?
(c) File proliferation - any new files that should be integrated?
(d) Cross-references - any stale paths or broken links?
(e) Technical debt - any workarounds, TODOs, or deferred issues?
(f) Test coverage (BLOCKING) - if skills/hooks modified, were tests written?
- No deployment without tests (skill-deployment.md § Step 0)
- v1.7.3 shipped without tests - this is the anti-pattern to prevent
(g) Issue resolution - any GitHub issues resolved? Close with details.
(h) Marketplace changes (BLOCKING) - if marketplace.json modified:
- Schema validated against Claude Code docs?
- All keys recognized (no `tools`, etc.)?
- hooks/mcpServers use .json config format?
- Installation tested end-to-end?
- v1.7.2-1.7.4 had invalid schema - this is the anti-pattern to prevent
Categorize findings as:
- [EXECUTE now] - do before session closes
- [DEFER to next session] - capture in resume
- [ASK user] - need decision/clarification
Depth adjustments:
- light: Brief check of each category, focus on obvious issues
- standard: Full analysis of each category
- thorough: Deep analysis, check file contents, verify cross-refs
Output format:
## Session Review Findings
### [EXECUTE now]
- Item 1
- Item 2
### [DEFER to next session]
- Item 1
### [ASK user]
- Question 1
### Summary
[1-2 sentence summary of session state]
Step 3: Validation Pass
Quick coverage check (not re-analysis):
After completing Step 2, verify you addressed:
- Git state - All work committed?
- Context docs - LOCAL_CONTEXT.md current?
- Planning docs - Any complete/stale?
- New files - Appropriate locations?
If any item missed, add to [EXECUTE now] or [DEFER] list.
Step 4: Project-Specific Checks
Check for project-specific cleanup checklist:
"${SKILL_BASE:-$HOME/.claude/skills/session-cleanup}/scripts/find_local_cleanup.sh" "${PROJECT_ROOT:-$PWD}"
If local file found (checked in order):
.claude/processes/local-session-cleanup.md(preferred)claude/processes/local-session-cleanup.md(legacy)
- Read the file
- Execute project-specific checks
- Add findings to appropriate category ([EXECUTE/DEFER/ASK])
If no local file: Skip this step (generic cleanup complete).
Step 5: Handoff to Session-Closure
Present findings and transition:
## Session Cleanup Complete
**Depth**: [light/standard/thorough]
**Findings**: [count] EXECUTE, [count] DEFER, [count] ASK
### Action Items
[List any [EXECUTE now] items to complete]
### For Resume
[List [DEFER] items to capture]
### Questions
[List [ASK] items needing user input]
---
When ready to close session, say "close context" or invoke session-closure.
Important: Session-cleanup does NOT auto-invoke session-closure (safety).
Additional Documentation
- references/README.md - Installation and usage guide
- references/LOCAL_TEMPLATE.md - Template for project-specific cleanup checklist
- references/CONTRIBUTING.md - Development and contribution guide
Session-cleanup skill v0.5.2 - Added category (h) marketplace validation (January 2026)
Source: christophera/claude_code_tools — distributed by TomeVault.