5.0 KiB
description, argument-hint
| description | argument-hint | |
|---|---|---|
| Save current conversation session to markdown file for future continuation |
|
Name
session:save-session
Synopsis
/save-session
/save-session [description]
Description
Saves the current conversation session to a comprehensive markdown file that enables seamless resumption of work after extended time intervals (days, weeks, or months).
This command addresses limitations of Claude Code's built-in session management by capturing:
- Complete conversation context and technical rationale
- Detailed file modification tracking with line numbers
- Key technical decisions and alternatives considered
- Commands executed during the session
- Clear resumption instructions
The generated session file is designed for engineers working across multiple projects with long gaps between sessions, providing all necessary context to continue work without losing momentum.
Implementation
The command follows a five-phase process:
Phase 0: Input Sanitization
If a description argument is provided, sanitize it for safe filename usage:
- Convert all spaces to hyphens
- Convert to lowercase
- Remove or replace special characters (keep only alphanumeric, hyphens, and underscores)
- Truncate to 100 characters maximum if longer
- Example: "investigating OCPBUGS-12345 regarding routes" → "investigating-ocpbugs-12345-regarding-routes"
Phase 1: Context Analysis
- Summarizes main topics and goals discussed
- Lists all accomplishments and completed tasks
- Identifies all files that were read, modified, or created
- Extracts important technical decisions and their rationale
- Captures any error messages encountered and how they were resolved
- Notes any commands that were run (make, linter, tests, etc.)
Phase 2: File Modification Tracking
- Reads and verifies current state of modified files
- Lists specific line numbers and code changes
- Includes before/after comparisons for critical changes
- Notes which files were created vs modified vs deleted
- Tracks any generated files (like bindata)
Phase 3: Session File Creation
Creates a comprehensive markdown document with these sections:
- Session Summary - Brief 1-2 paragraph overview
- Current State - Status of work and modifications
- Accomplishments - Detailed completion checklist
- Files Modified - Organized by Created/Modified/Deleted
- Key Technical Decisions - Rationale and implications
- Pending Tasks - Unfinished work (checkbox format)
- Commands Used - All executed commands
- Context for Resumption - Critical continuation information
- Full Conversation Summary - Key discussion points
- Next Steps - Clear action items
- How to Resume This Session - Step-by-step guide
Phase 4: Verification and Output
- Confirms file was created successfully
- Displays file path and size
- Provides brief summary of what was saved
- Shows resumption instructions in terminal and saved file
Return Value
Creates a markdown file in the repository root directory with filename:
session-YYYY-MM-DD-HHMM.md(without description)session-YYYY-MM-DD-<description>.md(with custom description)
Terminal output:
✅ Session saved successfully!
File: session-YYYY-MM-DD-description.md (XX KB)
Location: /full/path/to/file
📖 To resume this session:
Please read `/full/path/to/session-YYYY-MM-DD-description.md` and continue from where we left off
Examples
Basic usage with auto-generated timestamp:
/save-session
Creates: session-2025-10-16-1430.md
With custom description for easy identification:
/save-session parallel-test-fixes
Creates: session-2025-10-16-parallel-test-fixes.md
Multiple sessions in one project:
/save-session initial-implementation
/save-session pr-review-feedback
/save-session final-testing
With spaces and special characters (automatically sanitized):
/save-session investigating OCPBUGS-12345 regarding routes
Creates: session-2025-10-16-investigating-ocpbugs-12345-regarding-routes.md
Resuming a saved session: Open Claude Code and say:
Please read `/path/to/session-2025-10-16-parallel-test-fixes.md` and continue from where we left off
Arguments
description (optional)
- Custom identifier appended to the filename
- Helps identify the session purpose when resuming after long intervals
- Input handling: Description is automatically sanitized for safe filename usage (spaces converted to hyphens, special characters removed, truncated to 100 chars if needed)
- Good examples:
feature-name,bug-fix,refactoring,investigating-ocpbugs-12345 - Automatically added to filename:
session-YYYY-MM-DD-<description>.md
If no description is provided, timestamp alone is used: session-YYYY-MM-DD-HHMM.md
Note: You can use spaces and special characters in your description - they will be automatically sanitized. For example, "investigating OCPBUGS-12345 regarding routes" becomes "investigating-ocpbugs-12345-regarding-routes".