chatclerk

chatclerk converts LLM chat exports to directories of Markdown files. It supports ChatGPT, Claude, Grok, and Kagi Assistant exports, and preserves conversation structure, metadata, and associated assets such as generated images, artefacts, and file attachments.

It allows you to archive conversations from LLM services to storage under your control, to provide indefinite access independent of LLM service uptime or account closure, like you might archive emails from webmail services with isync or OfflineIMAP.

Each conversation is saved as a Markdown file named after its unique identifier, with metadata, timestamps, and messages formatted by role. Associated assets are saved in subdirectories matching the conversation filename.

Installation

chatclerk requires Python 3.14 or later. Install it from GitHub using uv with:

uv tool install git+https://github.com/srstevenson/chatclerk.git

Alternatively, you can clone the repository and install from source:

git clone https://github.com/srstevenson/chatclerk.git
cd chatclerk
uv tool install .

This will install the chatclerk-chatgpt, chatclerk-claude, chatclerk-grok, and chatclerk-kagi executables into ~/.local/bin. Ensure ~/.local/bin is in your shell's PATH.

Usage

chatclerk provides four command-line tools, one for each supported LLM service.

ChatGPT

To convert a ChatGPT export, download your data from https://chatgpt.com/#settings/DataControls and extract the archive. Then run:

chatclerk-chatgpt -i /path/to/chatgpt-export -o chatgpt-logs

This converts all conversations to Markdown files in the chatgpt-logs directory. Generated images and other assets are saved to subdirectories.

Claude

To convert a Claude export, download your data from https://claude.ai/settings/data-privacy-controls and extract the archive. Then run:

chatclerk-claude -i /path/to/claude-export -o claude-logs

This converts all conversations to Markdown files in the claude-logs directory. Artefacts and tool results are preserved in the output.

Grok

To convert a Grok export, download your data from https://grok.com/?_s=data and extract the archive. Then run:

chatclerk-grok -i /path/to/grok-export -o grok-logs

This converts all conversations to Markdown files in the grok-logs directory. Artefacts and file attachments are saved to subdirectories.

Kagi Assistant

To convert a Kagi Assistant export, download your data to JSON using kagi-asssistant-export.js from this repository. Paste it into the browser console on https://assistant.kagi.com; it downloads a file named like 2026-07-06-kagi-assistant-export.json. Then run:

chatclerk-kagi -i /path/to/2026-07-06-kagi-assistant-export.json -o kagi-logs

This builds Markdown from each conversation's messages and writes one Markdown file per conversation to the kagi-logs directory.

Development

chatclerk uses uv for dependency management and Ruff and ty for formatting, linting, and type checking, orchestrated with Just.

To clone the repository and set up a development environment run:

git clone https://github.com/srstevenson/chatclerk.git
cd chatclerk
uv sync

Format code and run the linter and type-checker with:

just fmt lint