conversation-logger

name

conversation-logger

description

This skill should be used when users need to save, search, or retrieve Claude Code conversation transcripts. Use this skill when users ask to save the current conversation, search through past conversations for context, or retrieve information from previous sessions. Also use when appropriate to proactively save important conversations at natural breakpoints (e.g., after completing a major feature, fixing a critical bug, or when the user indicates they're done with a session).

Conversation Logger

Overview

This skill enables systematic saving, searching, and retrieving of Claude Code conversation transcripts. It converts raw JSONL transcripts into readable markdown format and provides search capabilities across all saved conversations.

When to Use This Skill

Use this skill when:

• User explicitly asks to save the current conversation
• User wants to search through past conversations for context or information
• User asks about previous sessions or work done in earlier conversations
• Proactively saving important conversations at natural breakpoints (completed features, major bug fixes, end of work session)
• User needs to find when a specific topic, command, or issue was discussed

Core Capabilities

1. Save Current Conversation

To save the current conversation, use the save-conversation.sh script with the transcript path and optional session ID.

Script location: scripts/save-conversation.sh

Usage:

bash scripts/save-conversation.sh <transcript-path> [session-id]

Important: The transcript path is typically available as an environment variable or in the session context. Common locations:

• $CLAUDE_TRANSCRIPT_PATH (if set)
• ~/.claude/sessions/<session-id>/transcript.jsonl
• Check the current session directory for transcript files

What it does:

• Copies the JSONL transcript to ~/.claude/conversation-logs/
• Converts the transcript to readable markdown format
• Creates session metadata file
• Creates symlinks to the latest conversation for easy access

Output files created:

• conversation_YYYY-MM-DD_HH-MM-SS.jsonl - Raw transcript
• conversation_YYYY-MM-DD_HH-MM-SS.md - Human-readable markdown
• session_YYYY-MM-DD_HH-MM-SS.json - Session metadata
• conversation_latest.jsonl and conversation_latest.md - Symlinks to most recent

Example workflow: When a user says "save this conversation" or "log our work", first locate the transcript path, then execute the save script.

2. Search Through Saved Conversations

To search through saved conversations for specific terms or topics, use the search-conversations.sh script.

Script location: scripts/search-conversations.sh

Usage:

# Search for a term
bash scripts/search-conversations.sh "search-term"

# Search with more context lines
bash scripts/search-conversations.sh "search-term" --context 5

# List all saved conversations
bash scripts/search-conversations.sh --list

# Show recent conversations
bash scripts/search-conversations.sh --recent 5

Common search scenarios:

Finding when a topic was discussed:

bash scripts/search-conversations.sh "docker configuration"

Finding command usage:

bash scripts/search-conversations.sh "git commit" --context 10

Browsing recent work:

bash scripts/search-conversations.sh --recent 3

Example workflow: When a user asks "when did we work on the authentication bug?" or "find conversations about database migrations", use the search script to locate relevant conversations, then read the full conversation file if needed.

3. Retrieve Full Conversations

To read a complete saved conversation, access the markdown files directly in ~/.claude/conversation-logs/.

Typical workflow:

1. Use search to find relevant conversations
2. Note the timestamp from search results
3. Read the full markdown file: ~/.claude/conversation-logs/conversation_YYYY-MM-DD_HH-MM-SS.md

Quick access to latest:

cat ~/.claude/conversation-logs/conversation_latest.md

Conversation Format

Saved conversations are stored in two formats:

JSONL (Raw): Complete conversation data including all API messages, tool calls, and metadata. Used by the parser and for programmatic access.

Markdown (Readable): Human-friendly format with:

• Clear USER/ASSISTANT sections
• Tool usage summary (shows tool name and key parameters)
• Filtered system messages and noise
• Timestamps and session IDs

Proactive Usage Guidelines

Consider saving conversations proactively when:

• A complex feature or bug fix is completed
• User indicates they're wrapping up (phrases like "that's all for now", "thanks, I'm done")
• A significant amount of work has been accomplished in the session
• User switches context significantly (new project, different task domain)

Important: Always ask first before saving proactively. Example: "This looks like a good stopping point. Would you like me to save this conversation for future reference?"

Requirements

System dependencies:

• python3 - Required for parsing JSONL to markdown
• bash - For running the scripts
• jq - Optional, for working with JSON metadata

Installation check:

command -v python3 && echo "✓ Python installed" || echo "✗ Python required"

Troubleshooting

Cannot find transcript path:

• Check session directory: ls -la ~/.claude/sessions/
• Look for environment variables: env | grep CLAUDE
• Ask user for the transcript location

Parser fails:

• Verify python3 is installed and accessible
• Check that the JSONL file is valid (not corrupted)
• Fallback: Save only the JSONL file, skip markdown conversion

Search finds nothing:

• Verify conversations exist: ls ~/.claude/conversation-logs/
• Check that search term is spelled correctly
• Try broader search terms or use --list to see available conversations

Resources

scripts/

• save-conversation.sh - Main script to save and parse conversations
• search-conversations.sh - Search utility for finding past conversations
• parse-conversation.py - Python parser that converts JSONL to markdown

All scripts are executable and can be run directly from the skill directory.