Imported from ZENG3LD/claude-session-restore (skill/SKILL.md). Install upstream with npx skills add ZENG3LD/claude-session-restore --skill skill. Copyright stays with the author.

Session Restoration Skill

This skill helps restore full context when starting a new Claude session after a previous session was closed, crashed, or became too large.

When to Use

Use this skill when:

Starting a new session after a previous one ended
User asks to restore previous context
Session was interrupted or overflowed
User mentions "restore", "previous session", "last session"
User mentions (Russian): "восстанови", "восстанов", "предыдущая сессия", "прошлая сессия", "продолжи работу"

Restoration Process

Step 1: Find and Analyze Recent Session Files

Use the session-summary CLI tool to list recent sessions with automatic topic extraction:

# List recent sessions (default: last 12 hours, includes both projects/ and archive/)
session-summary.exe list

# Extend time window to 24 hours
session-summary.exe list --max-age-hours 24

# Only search projects directory (exclude archive)
session-summary.exe list --projects-only

What you'll see for each session:

Date/time: When it was last modified
Size: File size (indicates session length)
Source: [projects] or [archive]
Topic: Simple label (Agent tasks, User session, Tool usage, etc.)
Multi-vector data: Raw data from different event sources with emoji labels:
- 📋 Tasks - Agent task prompts
- 💬 User - User messages
- 🔧 Tools - Tool operations with file paths
- ⚙️ Bash - Bash command outputs
- 🔍 Search - Web search queries

Example output:

Recent Sessions:

1. 8f59d651-cada-4484-9153-5cc577137486
   Jan 26 04:33 | 32.42 MB | [projects] | Agent tasks
   📋 Tasks: Fix the dropdown z-order problem... → Fix the dropdown... → Fix the dropdown...
   💬 User: дропдауны либо с 0 опасити... → закомить работу...
   🔧 Tools: Bash, Bash, Bash, Write

2. 4e0b5d3d-c6d1-497d-9c6f-96e83980c7a0
   Jan 26 05:47 | 103.69 MB | [projects] | Agent tasks
   📋 Tasks: Implement MOEX ISS API connector... → Implement MOEX ISS API connector... → Implement MOEX ISS API connector...
   💬 User: <ide_opened_file>The user opened... → да, какие проблемы выявлены...
   🔧 Tools: Bash, Bash, Bash, Task, Task

3. 3162998f-09ca-4efc-b659-8507eb57bd37
   Jan 26 00:21 | 232.79 MB | [archive] | User session
   💬 User: Create 2-turn conversation test... → Run the tests...
   🔧 Tools: Task, Bash, Grep, Read, Write
   ⚙️ Bash: cargo check; compiling...

To load a session, use:
  1. session-summary.exe load "C:\Users\...\8f59d651-cada-4484-9153-5cc577137486.jsonl"
  2. session-summary.exe load "C:\Users\...\4e0b5d3d-c6d1-497d-9c6f-96e83980c7a0.jsonl"
  3. session-summary.exe load "C:\Users\...\3162998f-09ca-4efc-b659-8507eb57bd37.jsonl"

Ask user which session to restore, then copy-paste the corresponding load command

Step 2: Deep Dive into Selected Session

Once user selects a session, copy-paste the corresponding load command from the list output:

# Copy the full command from "To load a session" section above
session-summary.exe load "C:\Users\...\session-id.jsonl"

Example output:

═══════════════════════════════════════
Session: 8f59d651-cada-4484-9153-5cc577137486
═══════════════════════════════════════
Date: 2026-01-26 04:33:18
Size: 32.42 MB
Topic: Agent tasks

Agent Tasks 📋 (126 tasks)
  1. СРОЧНО! Dropdown перекрывается другими элементами (footer, другие UI)...
  2. Fix dropdown z-order problem in Chart Settings modal
  3. Implement hover states for dropdown items
  4. Add auto-sizing to dropdown containers
  ... (122 more)

User Messages 💬 (2 messages)
  1. закомить работу в ваших крейтах (чужую не комить)
  2. итого подведи итог что мы сделали по унификации...

Tool Operations 🔧 (7 operations)
  1. Task
  2. Bash
  3. Edit (zengeld-terminal/ui/chart_settings.rs)
  4. Read (zengeld-terminal/ui/dropdown.rs)
  ... (3 more)

Files Modified 📁 (17 files)
  1. zengeld-terminal/ui/chart_settings.rs
  2. zengeld-terminal/ui/dropdown.rs
  3. zengeld-terminal/ui/modal.rs
  ... (14 more)

Git Branch: zengeld-chart

The tool automatically:

Reads last segment of session from compact_boundary to end
Collects data from 6+ event types (AgentProgress, User, Assistant, BashProgress, QueryUpdate, FileSnapshot)
Shows all data vectors with counts and previews
Does NOT try to infer topics - just shows raw data
Extracts git branch and commit hints for further analysis

Step 3: Search Git History

Search for related commits to understand what was accomplished:

# Extract keywords from session (project names, features, etc.)
# Then search git log with those keywords

git log --all --oneline --grep="keyword1" --grep="keyword2" -i --since="1 week ago" | head -30

# Get detailed commit info
git show --stat <commit-hash>

Look for:

Commits made during or after the session timestamp
Commit messages describing the feature/fix being worked on
File changes that match the session's tracked files

Step 4: Analyze Multi-Vector Data & Provide Context Summary

IMPORTANT: The parser shows RAW DATA in multiple vectors. Your job is to ANALYZE this data and understand what was being worked on.

Look at all vectors:

Agent Tasks - What agents were doing (feature implementation, debugging, refactoring)
User Messages - What user was asking for, decisions made
Tool Operations - Which files were read/edited, what operations performed
Bash Activities - Build/test commands, git operations
Web Searches - Research topics, API documentation lookups
Files Modified - Scope of changes

Present a structured summary:

## Session Restoration Summary

**Session**: [session-id]
**Date**: [timestamp]
**Project**: [project-name]

### What Was Being Worked On:
[Analyze the multi-vector data to determine the main task/feature/bugfix]

### Files Being Worked On:
- path/to/file1.rs (main implementation)
- path/to/file2.rs (supporting changes)
- ...

### Related Git Commits:
- [hash] commit message (date)
- [hash] commit message (date)

### Context from Session Data:
- **Agent focus**: [from Tasks vector]
- **User requests**: [from User Messages vector]
- **Technical operations**: [from Tools/Bash vectors]

### Recommendations:
- Continue from: [specific file or task]
- Next steps: [based on commit history and unfinished work]

Important Notes

Session files can be VERY large (2GB+) - session-summary handles this efficiently
Tool uses tail + reverse parsing - reads from end, stops early
Multi-vector approach - parser collects raw data, you analyze it
Don't assume topic from label - "Agent tasks" is just a simple label, analyze the actual data
Git commits are the best context - they show what was actually accomplished
Timestamps help - cross-reference session time with commit times
Time filtering - default 12 hours, can extend to 24 hours with --max-age-hours

Example Usage

User: "restore previous session"
Assistant: [Runs restore-session skill]

I'll list recent sessions from the last 12 hours:

[runs: session-summary.exe list]

Recent Sessions:

1. 8f59d651-cada-4484-9153-5cc577137486
   Jan 26 04:33 | 32.42 MB | [projects] | Agent tasks
   📋 Tasks: Fix the dropdown z-order problem... → Fix the dropdown... → Fix the dropdown...
   💬 User: дропдауны либо с 0 опасити... → закомить работу...
   🔧 Tools: Bash, Bash, Bash, Write

2. 4e0b5d3d-c6d1-497d-9c6f-96e83980c7a0
   Jan 26 05:47 | 103.69 MB | [projects] | Agent tasks
   📋 Tasks: Implement MOEX ISS API connector... → Implement MOEX ISS API connector...
   💬 User: <ide_opened_file>... → да, какие проблемы выявлены...
   🔧 Tools: Bash, Bash, Task, Task

3. 3162998f-09ca-4efc-b659-8507eb57bd37
   Jan 26 00:21 | 232.79 MB | [archive] | User session
   💬 User: Create 2-turn conversation test... → Run the tests...
   🔧 Tools: Task, Bash, Grep, Read
   ⚙️ Bash: cargo check; compiling...

To load a session, use:
  1. session-summary.exe load "C:\Users\...\8f59d651-cada-4484-9153-5cc577137486.jsonl"
  ...

Which session would you like to restore? (1-3)

User: "1"
Assistant: [Runs the load command]

[runs: session-summary.exe load "C:\Users\...\8f59d651-cada-4484-9153-5cc577137486.jsonl"]

[Analyzes multi-vector data]

Based on the session data:
- **Main task**: Fixing dropdown z-order issue in Chart Settings modal
- **User requested**: Commit work in your crates, summarize unification work
- **Agent worked on**: UI dropdown rendering, z-order fixes, hover states
- **Files modified**: chart_settings.rs, dropdown.rs, modal.rs

[Searches git log for related commits]
[Provides full context summary]

Implementation Tips

Always start with the most recent sessions from the active project
Check both locations: ~/.claude/projects/ and ~/.claude/archive/
Parse JSONL carefully: Each line is a separate JSON object
Cross-reference: Session files + git log = complete picture
Ask user: If multiple sessions found, let user choose

Limitations

Cannot restore actual conversation history (that's internal to Claude)
Can only infer context from files and commits
Very old sessions might not have related commits anymore
Archived sessions may be compressed or incomplete

restore-session

About

Session Restoration Skill

When to Use

Restoration Process

Step 1: Find and Analyze Recent Session Files

Step 2: Deep Dive into Selected Session

Step 3: Search Git History

Step 4: Analyze Multi-Vector Data & Provide Context Summary

Important Notes

Example Usage

Implementation Tips

Limitations

Install restore-session and it becomes one more candidate the router can pick - when it fits.

Use it

Manifest

Reviews