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:

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:

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:

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:

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

# 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