---
description: Save current conversation session to markdown file for future continuation
argument-hint: [optional-description]
---

## 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:

1. **Session Summary** - Brief 1-2 paragraph overview
2. **Current State** - Status of work and modifications
3. **Accomplishments** - Detailed completion checklist
4. **Files Modified** - Organized by Created/Modified/Deleted
5. **Key Technical Decisions** - Rationale and implications
6. **Pending Tasks** - Unfinished work (checkbox format)
7. **Commands Used** - All executed commands
8. **Context for Resumption** - Critical continuation information
9. **Full Conversation Summary** - Key discussion points
10. **Next Steps** - Clear action items
11. **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".