---
name: session
description: Manage Claude Code sessions — save, reload, read, and search saved conversations. Triggers on /session commands or when user mentions saving session, reloading session, finding previous conversations, or continuing previous work.
---

# Session Management Skill

Save, reload, read, and search Claude Code sessions across conversations.

## Commands

| Command | Description |
|---------|-------------|
| `/session save` | Save current conversation with auto-generated title, summary, tags |
| `/session reload <id>` | Reload a session to continue working from where you left off |
| `/session read <id>` | View a session (read-only, no context load) |
| `/session search <query>` | Search sessions by keyword, tag, or date |

---

## /session save

### Auto-Save Mode
If triggered by `<auto-save-trigger>`, skip all confirmations and save immediately.

### Steps

1. **Analyze conversation** — main topics, problems solved, decisions made, files touched
2. **Generate title** — 5–10 words, descriptive (e.g. "Implement JWT Authentication with Refresh Tokens")
3. **Generate summary** with sections:
   - `context`: initial request or problem
   - `approach`: solution taken
   - `keyChanges`: main changes/implementations
   - `outcome`: what was achieved
   - `nextSteps`: what remains (if any)
4. **Extract tags** — 3–8 tags: technologies, task type, domain
5. **Get session ID** — check `~/.claude/hooks/.current-session`; if missing, use `YYYY-MM-DD_HHmm`
6. **Filter conversation before saving:**
   - EXCLUDE: bash outputs, full file reads, tool results, `<system-reminder>` tags, stack traces
   - INCLUDE: user requests, assistant reasoning, decisions, file paths modified, code changes summary
7. **Save to** `~/.claude/sessions/<id>_<sanitized-title>.json`:
   ```json
   {
     "id": "YYYY-MM-DD_HHmm",
     "title": "...",
     "date": "ISO 8601",
     "timestamp": 1234567890,
     "tags": ["tag1", "tag2"],
     "summary": {
       "context": "...", "approach": "...", "keyChanges": "...",
       "outcome": "...", "nextSteps": "..."
     },
     "metadata": { "messageCount": 0, "technologies": [], "filesModified": [] },
     "conversation": [
       { "role": "user|assistant", "content": "...", "toolSummary": "optional" }
     ]
   }
   ```
8. **Update index** `~/.claude/sessions/index.json` — add entry, sort by date desc
9. **Post-save** — run `~/.claude/hooks/autosave-mark.sh`, delete `~/.claude/hooks/.pending-save`
10. **Confirm** — show session ID, filename, title, tags

### Output (manual mode)
```
Session saved!
ID: 2026-01-20_1430
Title: Implement Dark Mode Toggle Feature
Tags: react, css, ui, feature
File: ~/.claude/sessions/2026-01-20_1430_implement-dark-mode-toggle-feature.json
To reload: /session reload 2026-01-20_1430
```

### Output (auto-save)
```
[Auto-saved] 2026-01-20_1430: "Implement Dark Mode Toggle Feature" (45 messages)
```

---

## /session reload `<id>`

Load a session to **continue working** from where it left off.

### Steps

1. **Resolve ID** — accept exact ID, partial, or keywords; search index.json if ambiguous
2. **Load** `~/.claude/sessions/<id>_<title>.json`
3. **Display context:**
   ```
   Loaded: [Title]
   Date: YYYY-MM-DD HH:mm (X days ago) | Tags: ... | Messages: N
   Files Modified: file1, file2

   Context: ...
   Approach: ...
   Key Changes: ...
   Outcome: ...
   Next Steps: ...

   Session loaded. What would you like to work on?
   ```
4. **Maintain context** — reference session details, remember modified files, continue naturally
5. **Offer options** based on Next Steps

---

## /session read `<id>`

View a session **without** loading it as active context.

### Steps

1. Resolve ID (same as reload)
2. Load and display — show metadata + summary by default
3. **Modes:**
   - Default: metadata + summary only
   - `--full`: full conversation history
   - `--messages N-M`: specific message range
4. End with actions: reload link, search link

---

## /session search `<query>`

Search saved sessions.

### Steps

1. Load `~/.claude/sessions/index.json`
2. Parse query — keywords, tags (`tag:react`), dates (`last week`, `January`)
3. Search index first (fast); load individual files only for full-content search
4. Display results (newest first, limit 10):
   ```
   Found 3 sessions matching "react":

   1. [2026-01-20_1430] Implement Dark Mode Toggle Feature
      Jan 20, 14:30 | react, css, ui
      Added dark mode toggle to application settings...

   To reload: /session reload <id>
   ```
5. If single result, offer to reload automatically

### Query syntax
- Keywords: `search react authentication`
- Tag filter: `tag:bug-fix`
- Date: `last week`, `today`, `January 2026`
- Boolean: `react AND jwt`, `react OR vue`, `react NOT bug`
- All: `list all sessions`