claude-transcript

Convert Claude Code JSONL conversation files to readable markdown transcripts.

👀 Checkout .claude-transcripts to see the sessions I had to actually build this tool.

Features

• 🚀 Auto-detects JSONL files from ~/.claude/projects/ directory
• 📝 Converts conversations to clean, readable markdown format
• 🖼️ Preserves images by extracting them to the output directory
• 🛠️ Formats tool usage with appropriate emojis and syntax highlighting
• 📂 Organizes output in .claude-transcripts/ directory
• 🏷️ Generates descriptive filenames with timestamps and conversation preview

Installation

You can run claude-transcript directly using npx (no installation required):

npx claude-transcript

Or install it globally:

npm install -g claude-transcript

Usage

Basic Usage

Run in your project directory to auto-detect JSONL files:

npx claude-transcript

This will look for JSONL files in ~/.claude/projects/<sanitized-current-directory>/

Specify JSONL Directory

You can also specify a custom JSONL directory:

npx claude-transcript /path/to/jsonl/folder

CLI Options

Debug Mode

For detailed output including line numbers and processing information:

npx claude-transcript --debug

Custom Output Directory

Specify a custom output directory (default is .claude-transcripts):

npx claude-transcript --output custom-output-dir

This is useful for testing or organizing transcripts in different locations.

Show Version

Display the current version:

npx claude-transcript --version

Show Help

Display help information with all available options:

npx claude-transcript --help

Combining Options

You can combine multiple options:

npx claude-transcript /path/to/jsonl --output test-output --debug

Output

Transcripts are saved to .claude-transcripts/ in your current directory with:

• Markdown files named with timestamp and first 5 words of conversation
• Images and other results, like diffs, extracted to .claude-transcripts/contents/
• Clean formatting with:
  • User messages in blockquotes with [!IMPORTANT] tag
  • Tool usage with emojis and syntax highlighting

Example Output

# 🤖 Claude Code Transcript

## 🗂️ ~/Projects/my-app

🕒 2025-01-22 18:19:02 - 2025-01-22 18:45:23

> [!IMPORTANT]
> Help me refactor this code to be more maintainable

I'll help you refactor the code. Let me first examine the current structure...

📖 **Read: `src/index.ts`**

Requirements

• Node.js v24 or higher (uses native TypeScript type-stripping support)

Development

1. Clone the repository:

git clone https://github.com/kiliman/claude-transcript.git
cd claude-transcript

2. Install dependencies:

pnpm install

3. Run locally:

node src/index.ts

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

If you find any bugs or have feature requests, please file them at https://github.com/kiliman/claude-transcript/issues