open-context open-context
October 11, 2026 · 6 min read

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 NormalizedConversation schema (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.