Claude Code Sessions to Markdown

Export your Claude Code CLI sessions to Markdown files for viewing in Obsidian or any other markdown editor.

Overview

This Ruby script reads your Claude Code session data from the local storage directory (~/.claude/) and exports each session as a well-formatted Markdown file. The exported files include:

• Session metadata (title, creation date, directory, etc.)
• Full conversation history between you and Claude
• Tool usage and results
• Thinking and reasoning blocks (collapsible)
• Proper formatting for easy reading in Obsidian

Features

• Incremental Export: Only exports sessions that haven't been exported before
• Obsidian Compatible: Generated markdown works seamlessly with Obsidian
• Rich Formatting: Includes frontmatter, timestamps, and organized conversation flow
• No Duplicates: Tracks exported sessions to avoid re-exporting

Requirements

• Ruby 3.0 or higher
• Claude Code CLI installed and configured
• An Obsidian vault (or any directory for markdown files)

Installation

1. Clone or download this repository
2. Install dependencies:

bundle install

3. Copy the example environment file and configure it:

cp .env.example .env

4. Edit .env and set your Obsidian vault path:

OBSIDIAN_PATH=/path/to/your/obsidian/vault
CLAUDE_SESSIONS_SUBDIR=Claude Sessions  # Optional, defaults to "Claude Sessions"
CLAUDE_STORAGE_PATH=~/.claude  # Optional, defaults to ~/.claude

Usage

Run the export script:

ruby export.rb

Or make it executable:

chmod +x export.rb
./export.rb

Command Line Options

You can override environment variables with command line options:

ruby export.rb --help                           # Show all options
ruby export.rb -o /path/to/vault                # Specify Obsidian path
ruby export.rb -c ~/.claude -s "My Sessions"    # Custom storage and subdirectory
ruby export.rb --debug                          # Show backtraces on errors

Option	Short	Description
--obsidian-path	-o	Path to Obsidian vault (overrides OBSIDIAN_PATH)
--claude-storage-path	-c	Path to Claude storage (default: ~/.claude)
--sessions-subdir	-s	Subdirectory for sessions (default: "Claude Sessions")
--debug	-d	Show debug output including backtraces

The script will:

1. Read all sessions from ~/.claude/ (or your custom CLAUDE_STORAGE_PATH)
2. Parse session history from ~/.claude/history.jsonl
3. Load session conversations from ~/.claude/projects/{project-path}/{sessionId}.jsonl
4. Check which sessions have already been exported
5. Export new sessions to <OBSIDIAN_PATH>/Claude Sessions/
6. Track exported sessions to avoid duplicates

Example Output

Starting Claude Code session export...
Obsidian path: /home/user/Documents/Obsidian
Output directory: /home/user/Documents/Obsidian/Claude Sessions

Successfully exported 3 new session(s):
  - ses_431b70570ffetNNpEZ3cI5LQwQ
  - ses_431a6c7a5ffeCKPQ9aAOzhFkkp
  - ses_41d04ee29ffexfKgqz82X5XpTv

Done! Check your Obsidian vault at: /home/user/Documents/Obsidian/Claude Sessions

Markdown File Format

Each exported session is saved as a markdown file with the following structure:

---
title: Session Title
session_id: ses_xxxxx
slug: session-slug
created: 2024-01-17 12:30:00
updated: 2024-01-17 12:45:00
directory: /path/to/project
version: 1.0.0
tags: [claude-code, session]
---

# Session Title

**Session ID**: `ses_xxxxx`
**Created**: 2024-01-17 12:30:00
**Updated**: 2024-01-17 12:45:00
**Directory**: `/path/to/project`

---

## 👤 User

*2024-01-17 12:30:05*

User message here...

---

## 🤖 Assistant

*2024-01-17 12:30:15*

Assistant response here...

<details>
<summary>💭 Thinking</summary>

Thinking process...

</details>

---

Development

Running Tests

The project uses RSpec for testing:

bundle exec rspec

To run tests with verbose output:

bundle exec rspec --format documentation

Project Structure

.
├── lib/
│   └── claude_code_session_exporter.rb  # Main exporter class
├── spec/
│   ├── spec_helper.rb
│   └── claude_code_session_exporter_spec.rb
├── export.rb                            # CLI script
├── Gemfile
├── .env.example
├── .gitignore
└── README.md

How It Works

1. Session Discovery: The script reads ~/.claude/history.jsonl to find all session IDs and metadata
2. Session Loading: For each session, it locates the corresponding JSONL file in ~/.claude/projects/{project-path}/{sessionId}.jsonl
3. Message Parsing: The JSONL file is parsed line-by-line to extract all conversation messages (user and assistant)
4. Content Extraction: Messages contain text, tool usage, thinking blocks, and other conversation elements
5. Markdown Generation: Sessions are converted to markdown with YAML frontmatter and formatted conversation
6. Export Tracking: A hidden .exported_sessions.json file tracks which sessions have been exported to avoid duplicates

Configuration Options

Configuration can be set via environment variables (in .env) or command line options. CLI options take precedence over environment variables.

Environment Variables

• OBSIDIAN_PATH (required unless using -o): Path to your Obsidian vault or markdown directory
• CLAUDE_SESSIONS_SUBDIR (optional): Subdirectory name within your vault (default: "Claude Sessions")
• CLAUDE_STORAGE_PATH (optional): Path to Claude Code storage directory (default: "~/.claude")

Customization

You can modify lib/claude_code_session_exporter.rb to customize:

• Markdown formatting
• Frontmatter fields
• How tool usage is displayed
• Thinking block styling
• Session title extraction logic

Troubleshooting

"Claude storage path not found" error

Make sure Claude Code is installed and you've run it at least once. The storage directory (~/.claude/) is created automatically by Claude Code when you first run it.

"Obsidian path not found" error

Check that your OBSIDIAN_PATH in .env points to an existing directory.

No sessions found

If you've just installed Claude Code, you may not have any sessions yet. Use Claude Code to have a conversation, then run the export script again.

License

MIT License - feel free to use and modify as needed.

Contributing

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