From ChatGPT Export to Claude Format: Inside the Pipeline
open-context converts a ChatGPT export into Claude-ready markdown in four stages: it extracts
the ZIP, parses conversations.json by walking each conversation's message tree,
normalizes every message into one shared schema, and generates per-conversation markdown plus an
index. Every stage is a plain function call on your own machine — nothing is uploaded, and the
same normalized schema is what lets open-context support new
providers without touching the rest of the pipeline.
Key takeaways
- The pipeline has four stages: extract, parse, normalize, generate — each implemented as its own module in
src/. - ChatGPT doesn't export a flat list of messages; it exports a tree. The parser does a breadth-first walk of that tree to reconstruct conversation order.
- Every provider's output funnels into one
NormalizedConversationschema (id,title,created,updated,messages[]) — formatters and exporters only ever read that shape. - Invalid or empty messages and conversations are filtered out during parsing and normalization, before any file is written.
- The web UI's Pipeline page visualizes these same stages live — uploading, parsing, normalizing, analyzing, exporting, complete.
Why a "pipeline" instead of one conversion function
It would be possible to read conversations.json and write markdown in a single pass.
open-context doesn't, because ChatGPT's export format is not the only one it needs to support —
Google Gemini via Takeout is on the roadmap, and the project's own
guide to writing a new provider parser
exists specifically because the pipeline is designed to grow. Splitting extraction, parsing,
normalization, and generation into separate stages means a new provider only has to solve one
problem — turning its export into the shared schema — without touching how markdown gets written
or how the MCP store works.
Stage 1: Extraction
A ChatGPT data export arrives as a ZIP file. src/extractor.ts's ZipExtractor
unzips it into a temporary directory with adm-zip, confirms conversations.json
is actually present (failing fast with a clear error if it isn't), and notes whether optional
files like user.json or an images/ directory exist. Everything downstream
reads from this temp directory, which gets cleaned up once conversion finishes.
Stage 2: Parsing — walking a tree, not a list
This is the stage most people get wrong when they first open conversations.json.
ChatGPT doesn't store a conversation as an ordered array of messages. Each conversation has a
mapping — a dictionary of message nodes, each pointing to a parent and a list of
children — because ChatGPT supports branching (regenerated responses, edited messages) that a
flat array can't represent.
ChatGPTParser.walkMessageTree() in src/parsers/chatgpt.ts finds the root
node (the one with no parent), then does a breadth-first traversal, visiting each node once and
pushing its message onto an ordered array whenever that node passes an isValidMessage
check. That check exists because the tree contains nodes that shouldn't become visible messages
at all: system messages with no content, or nodes whose content.parts and
content.text are both empty. Filtering happens here, during the walk, not as a
separate cleanup pass afterward.
Stage 3: Normalizing — one schema for every provider
Parsing gets you ChatGPT's own shapes — author.role values like tool,
timestamps as Unix seconds, content buried under content.parts or
content.text depending on message type. None of that is what the rest of the
pipeline wants to work with. ConversationNormalizer in
src/parsers/normalizer.ts converts each parsed conversation into the schema every
other part of open-context — the markdown formatter, the vendor exporters, the preference
analyzer — actually reads:
interface NormalizedConversation {
id: string
title: string
created: Date
updated: Date
messages: NormalizedMessage[]
}
interface NormalizedMessage {
role: 'user' | 'assistant' | 'system'
content: string
images?: string[]
timestamp: Date
metadata?: { model?: string; attachments?: string[] }
}
Role mapping is intentionally lossy in one direction: ChatGPT's tool author role
collapses into assistant, since the normalized schema has no separate concept of a
tool call. Timestamps convert from Unix seconds to JavaScript Date objects.
Image references come from two different places in the raw message — inline
asset_pointer fields and image-typed attachments — and both get merged into a single
images array.
After normalization, isValidConversation() runs a second filter: any conversation
with zero messages, or where none of its messages has actual text content, gets dropped before it
ever reaches a formatter. A ChatGPT export can contain conversations that are empty, abandoned, or
entirely composed of system scaffolding — this is where those get removed.
Stage 4: Generating output
MarkdownFormatter in src/formatters/markdown.ts turns each
NormalizedConversation into a standalone markdown file — a title, created/updated
metadata, then each message as a ## User or ## Assistant section — plus
one index file summarizing every conversation that was kept. If you don't pass
--skip-preferences, a fifth, optional step runs before generation finishes: the
Ollama-backed preference analyzer reads across the normalized conversations and writes
preferences.md and memory.md, the two files the
ChatGPT-to-Claude migration guide
walks through pasting into Claude's settings.
Watching it happen in the web UI
The CLI prints each stage as a log line as it runs. The web UI's Pipeline page goes further: it
tracks an explicit PipelineStage — uploading, parsing,
normalizing, analyzing, exporting, complete, or
error — in React state and renders it as a live progress row with a spinner on the
active stage and checkmarks on completed ones. It's the same four-stage pipeline underneath; the
UI just gives it a face so you can see which conversation is being processed and how many were
kept versus dropped.
See the pipeline run on your own ChatGPT export.
Get started with open-context →FAQ
What does "normalizing" a conversation actually mean?
Normalizing means converting a provider's raw export format into open-context's shared schema — a conversation with an id, title, created/updated timestamps, and an ordered array of messages, each with a role of user, assistant, or system, plus content, a timestamp, and optional images or metadata. Every formatter and exporter downstream only ever reads this one schema.
Does the pipeline support providers other than ChatGPT?
ChatGPT is the only fully implemented parser today; Gemini support via Google Takeout is planned. The pipeline is built so a new provider only needs a new parser that outputs the same normalized schema — the normalizer, formatter, and MCP store code don't change.
What happens to messages the parser can't read?
The ChatGPT parser's isValidMessage check drops system messages with no content and any message with neither text nor content parts before normalization. After normalization, isValidConversation drops any conversation left with zero messages or no message containing actual text, so broken or empty threads from a partial export never reach your output files.
Can I watch the conversion pipeline run, or does it happen invisibly?
In the web UI, the Pipeline page visualizes every stage — uploading, parsing, normalizing, analyzing, exporting, complete — as a live progress row with checkmarks. The CLI prints the same stages as plain log lines (extracting, parsing, normalizing, generating) as they happen.
Does any part of the pipeline send my conversations to a server?
No. Extraction, parsing, normalization, and markdown generation all run as local function calls with no network access. The only possible outbound call in the whole pipeline is to an Ollama instance you control, and only during the optional preference-analysis step.