---
name: share-session
description: Convert and share Claude Code conversation sessions as readable markdown files. Use when user wants to share a session transcript, export conversation history, or create a shareable markdown document from a Claude Code session. Triggered by requests like "share this session", "export conversation", "convert session to markdown".
---

# Share Session

## Overview

Convert Claude Code sessions into readable markdown format for easy sharing. This skill finds sessions by fuzzy matching todo items and generates well-formatted markdown documents.
If this is loaded by user's explicit request but no comments there, just execute followings.

## Workflow

### Step 1: CRITICAL - Create Todo for Session Identification

**MANDATORY**: You MUST use TodoWrite tool to create a todo item that describes **what this session is about**.

**IMPORTANT**: You do NOT need to know the session ID. Describe the session content instead.

**CORRECT Usage:**
```python
TodoWrite(todos=[{
    "content": "share this session about ccusage integration and time tracking",
    "status": "in_progress",
    "activeForm": "Sharing session"
}])
```

**Good Examples (describe session topic):**
- ✅ "share this session about ccusage integration"
- ✅ "export conversation on implementing time tracking"
- ✅ "share current session with share-session improvements"

**Bad Examples (using session ID directly):**
- ❌ "get session id of 62d3a2b2-102c-43d3-8414-0a30d7a5e5e0" (you don't know session ID yet!)
- ❌ "export 62d3a2b2" (session ID unknown)

**How it works:**
1. You create todo with **session description**
2. Claude Code saves todo as: `~/.claude/todos/{SESSION-ID}.json`
3. Script searches todo **content** using fuzzy matching (60% threshold)
4. Script extracts SESSION-ID from the matching todo **filename**
5. Script uses that SESSION-ID to find transcript

**Why this is required:**
- Without a todo, the script has no way to identify which session to export
- The todo file name is the ONLY place where session ID is stored
- Fuzzy matching allows flexible queries ("share this session" matches multiple variations)

**Common mistakes:**
- ❌ Forgetting to call TodoWrite before running the script
- ❌ Using session ID in todo content (you don't know it yet!)
- ❌ Query in Step 2 doesn't match todo content at all

### Step 2: Run share_session.py

**IMPORTANT**: Always use the ABSOLUTE path to the script:

```bash
uv run --script /Users/yeongyu/local-workspaces/advanced-claude-code/claude-code-plugins/cc-plus/skills/share-session/scripts/share_session.py "your search query"
```

**The search query should match your todo content from Step 1.**

The script automatically:
- Searches todos using fuzzy matching (60% threshold)
- Locates transcript at `~/.claude/projects/*/{session-id}.jsonl`
- Merges pre-compact backups if they exist
- **Fetches accurate cost/token data from ccusage** (NOT LiteLLM)
- Converts to markdown with full statistics
- **Truncates before /share command** (excludes the share request itself)
- Saves to `/tmp/claude-code-sessions/{session-id}-{timestamp}.md`
- Copies the file path to clipboard
- Displays success message with cost breakdown

### Step 3: Output

The script displays:
```
✅ Markdown saved to:
/tmp/claude-code-sessions/{session-id}-{timestamp}.md

💰 Total Session Cost: $X.XXXXXX

📋 The path has been copied to your clipboard.
```

## Generated Markdown Format

The script generates comprehensive markdown with:

**Session Metadata:**
- 📊 Session ID, generation timestamp, message count
- 🔄 Models used (from ccusage data)

**Content:**
- 💬 User messages with timestamps (meta messages filtered)
- 🤖 Assistant responses with timestamps
- 🧠 Thinking process (when available, shown as nested quotes)
- 🔧 Tool usage details (collapsed in `<details>` tags)
- 🚀 Subagent calls (Task tool usage)

**Cost & Token Statistics (from ccusage):**
- 💰 Total session cost (accurate calculation from ccusage)
- 📊 Token breakdown:
  - Input tokens
  - Output tokens
  - Cache creation tokens
  - Cache read tokens
  - Total tokens
- 🎯 Cache hit rate percentage
- 📉 Average cost per message

**Session Timeline (NEW):**
- ⏱️ **Total Session Time**: First message → Last message
- 🟢 **LLM Active Time**: User question → Last assistant response (per turn)
- 🟡 **LLM Idle Time**: Last assistant → Next user question
- 📊 **LLM Utilization**: (Active Time / Total Time) × 100%

**Special Features:**
- 📦 Compact markers shown for merged pre-compact backups
- 🔪 Auto-truncates before `/share` command (excludes the export request itself)
- 🔄 Multi-model support (tracks different models per message)

## Script

### share_session.py

**The only script you need.** Does everything from search to markdown generation.

**Usage:**
```bash
uv run --script /Users/yeongyu/local-workspaces/advanced-claude-code/claude-code-plugins/cc-plus/skills/share-session/scripts/share_session.py <query>
```

**Dependencies (auto-installed by uv):**
- `orjson`: Fast JSON parsing
- `thefuzz`: Fuzzy string matching for todo search
- `rich`: Terminal formatting and progress display

**Complete features:**
- ✅ Fuzzy search through todo files (60% threshold)
- ✅ Automatic pre-compact backup merging
- ✅ **Accurate cost/token data from ccusage** (via `bunx --bun ccusage session -i`)
- ✅ **Turn-based time tracking**:
  - LLM Active Time (user → last assistant per turn)
  - LLM Idle Time (last assistant → next user)
  - Utilization percentage
- ✅ Auto-truncation before `/share` command
- ✅ Multi-model session support (from ccusage data)
- ✅ Clipboard integration (macOS `pbcopy`)
- ✅ Rich terminal output with colored progress
- ✅ TypedDict-based type safety

**Output:** File path (stdout) + clipboard

**Exit codes:**
- 0: Success
- 1: Session not found or conversion failed

**Performance:**
- Typical execution: 2-5 seconds
- Timeout: 30 seconds (for ccusage call)

## Error Handling

**No session found:**
- ❌ **Cause**: Todo item not created or query doesn't match
- ✅ **Solution**:
  1. Verify you called `TodoWrite` in Step 1
  2. Check query matches todo content (60% fuzzy threshold)
  3. Try exact session ID if known

**Transcript not found:**
- ❌ **Cause**: Session ID extracted but transcript missing
- ✅ **Solution**:
  1. Confirm session ID is correct
  2. Check `~/.claude/projects/` directory exists
  3. Look for `{session-id}.jsonl` file
  4. Check pre-compact backups at `~/.claude/pre-compact-session-histories/`

**ccusage data fetch failed:**
- ⚠️ **Symptom**: "Could not fetch session usage data from ccusage"
- ❌ **Possible causes**:
  1. `ccusage` command not available (check `bunx --bun ccusage --version`)
  2. Session ID not found in ccusage database
  3. JSON parsing error from ccusage output
- ✅ **Impact**: Markdown still generated but without cost/token statistics
- ✅ **Fallback**: Warning message displayed, conversion continues

**Conversion failed:**
- ❌ **Cause**: JSONL parsing or markdown generation error
- ✅ **Solution**:
  1. Check transcript file is valid JSONL (each line = valid JSON)
  2. Review error message from stderr
  3. Check for corrupted transcript data

**Clipboard copy failed:**
- ⚠️ **Symptom**: "Warning: Could not copy to clipboard"
- ❌ **Cause**: `pbcopy` command failed (macOS only)
- ✅ **Impact**: Non-critical - file path still shown in stdout
- ✅ **Workaround**: Manually copy the displayed path

## Troubleshooting

**Script says "No session found" even though todo exists:**
```bash
# Check if todo file exists
ls -la ~/.claude/todos/ | grep $(date +%Y-%m-%d)

# Verify todo content
cat ~/.claude/todos/{session-id}*.json | jq .
```

**Want to export specific session by ID:**
```bash
# Create todo with exact session ID
TodoWrite(todos=[{"content": "export {exact-session-id}", "status": "in_progress", "activeForm": "Exporting"}])

# Then run with session ID
uv run --script ... "{exact-session-id}"
```

**ccusage returns wrong data:**
- Verify ccusage version: `bunx --bun ccusage --version`
- Test ccusage directly: `bunx --bun ccusage session -i {session-id} --json`
- Check if session exists: `bunx --bun ccusage session`