Convoviz turns a ChatGPT export ZIP into Markdown, word clouds and usage graphs

The gap between OpenAI's export ZIP and a usable archive

OpenAI's data export arrives as a ZIP whose main payload is JSON. That JSON is built for transport, not for reading: conversations are stored as node trees, messages carry metadata, and attachments live as separate files inside the archive. If you want to search your history, quote it in a document, or keep it next to your notes, the ZIP is a starting point rather than a destination.

Convoviz exists to close that gap. According to the README, it converts the export into "clean, readable Markdown (text files)" and is described as suitable for "archiving, local search, or use with note-taking apps like Obsidian." The audience is therefore narrow and specific: people who already work in plain text, and people who want their own conversation data in a format they control.

The second audience is smaller but real. The project also generates word clouds and usage graphs, so someone who is curious about how they use ChatGPT, which words recur, or when they tend to open it, gets a direct answer without writing a parser.

How Convoviz reads the export and what it writes out

The input is a single ZIP. The output is a folder tree. In between, Convoviz parses the conversation JSON, walks the message structure, and renders each conversation as a Markdown file. The README describes two rendering choices that matter here. The markdown render order can be set to `active` (the default, meaning the current branch) or `full` (all DAG branches). That distinction exists because ChatGPT conversations are stored as a graph, and edited or regenerated messages create branches. Choosing `active` gives you the thread you actually saw; choosing `full` preserves the alternatives, at the cost of a longer file.

The second choice is markdown flavor: `standard` by default, or `obsidian`, which the README says produces "collapsible callouts for reasoning content." That is a deliberate bet on one editor's syntax rather than a generic Markdown feature.

Beyond the transcript, Convoviz extracts side artifacts. Media attachments are rendered inline in the Markdown. Web search results and source links are preserved as citations. OpenAI Canvas documents are written out as standalone files with their own extensions such as `.py` or `.html`. User and model system messages go to `custom_instructions.json`. Each of these is a separate output path, which is why the CLI lets you select which outputs to generate rather than always producing everything.

Installing Convoviz and converting your first export

The README offers a one-line installer for macOS and Linux, and a PowerShell equivalent for Windows. It also documents a pip path for people who prefer to manage their own environment. The pip route creates a virtual environment first, which keeps the visualization dependencies out of your system Python.

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install "convoviz[viz]"

The `[viz]` extra is what pulls in the visualization stack; `pyproject.toml` lists `nltk` and `wordcloud` as the optional `viz` dependencies, while core dependencies include `orjson`, `pydantic`, `typer` and `rich`. If you only want Markdown, the extra is not required.

With the tool installed, the simplest run is the interactive one. It prompts for the input ZIP and the output folder.

convoviz

To skip the prompts, pass the paths directly. The README gives this exact form:

convoviz --input path/to/your/export.zip --output path/to/output/folder

If you want to keep the first run small, restrict the outputs. The `--outputs` flag accepts `markdown`, `graphs` and `wordclouds`, and can be repeated:

convoviz --input export.zip --outputs markdown --outputs graphs

After the run, the output folder contains the Markdown files, any visualizations you asked for, extracted Canvas documents, and `custom_instructions.json`. The README states the default output location is `Documents/ChatGPT-Data` when you do not override it. One flag worth knowing before a second run is `--flat`, which places all Markdown files in a single folder instead of organizing them by date; the default grouping is date-based, so a flat archive is a conscious departure from it.

Configuration, and why the defaults may not suit a notes vault

Convoviz reads a TOML config file. Defaults ship with the package, and `convoviz config init` writes a user config you can edit. The README lists the default locations per platform: `~/.config/convoviz/config.toml` on Linux, `~/Library/Application Support/convoviz/config.toml` on macOS, and `%APPDATA%\convoviz\config.toml` on Windows. A custom path can be passed with `--config`.

convoviz config init

Several settings change the shape of the output rather than its content. `conversation.markdown.show_timestamp` toggles timestamps inside the Markdown. `wordcloud.include_assistant_text = false` limits word clouds to your own messages, which is the setting you want if the cloud is meant to describe you rather than the model. Word cloud layouts are deterministic by default, and the README notes that setting `wordcloud.random_state = ""` disables that determinism. Determinism is the better default for a file you might regenerate and diff; the escape hatch is there if you want a different layout each time.

One detail deserves attention if you plan to sync the output into a vault. The README states that YAML frontmatter titles are sanitized, and that when the title changes, the original is preserved in `aliases`. Sanitizing is necessary because conversation titles can contain characters that break YAML, but it means the title you see in frontmatter is not always the title ChatGPT stored. The `aliases` field is the recovery path.

Merging a second export without duplicating conversations

ChatGPT exports are snapshots, not streams, so the natural workflow is to export again later and merge. The README documents a direct export script under `js/` with its own `js/HOW_TO_USE.md`, intended for grabbing recent conversations without waiting on the official export. If a `convoviz_export.zip` is present in your Downloads folder, Convoviz will ask whether to merge it.

The merge behavior is described as "additive and smart": you can combine multiple runs into the same output folder, and Convoviz uses identity-based overwriting to update existing chats rather than creating duplicates. That is the right design for this problem, because filename-based deduplication would break the moment a conversation title changed.

The limitation is that this is still a merge of whole snapshots. The README does not describe a way to remove conversations from the output when they disappear from a later export, and it does not document rollback. If you need the output folder to be an exact mirror of the current account state, this is not that tool; treat the folder as an accumulating archive instead.

Where Convoviz is the wrong choice

The first case is scale. Convoviz renders every conversation into its own file and, for word clouds, tokenizes the corpus with `nltk`. That is fine for a personal history and increasingly awkward for an account with years of heavy use, especially if you enable `full` render order and keep every branch. The README does not document a streaming mode or an incremental render, so a re-run reprocesses the export.

The second case is anyone who wants to read their history without producing files. Convoviz has no viewer and no server; the output is a folder. If you want to browse conversations in a UI, converting to Markdown is a step you do not need.

The third case is teams. The tool reads a personal export ZIP and writes to a local folder. There is no documented multi-user mode, no shared index, and no access control. Using it on someone else's export is a data-handling decision the tool does not make for you.

The fourth case is fidelity. The `active` render order is the default, which means edited and regenerated branches are dropped from the Markdown unless you switch to `full`. If your reason for archiving is to preserve exactly what was generated, the default works against you, and the README's config section is where you change it.

How Convoviz differs from a JSON-to-Markdown script you write yourself

The honest alternative is a short Python script over the export JSON. The parsing is not the hard part; the mapping is. Convoviz has already decided how to handle branch selection, how to render citations, how to inline media, how to name files, and how to sanitize frontmatter titles while keeping the original in `aliases`. A script you write will make those decisions differently and will need maintenance each time the export format shifts.

The trade-off runs the other way too. Convoviz is a general-purpose converter with a fixed set of options, and its behavior is defined by its config schema. If your vault has a specific frontmatter contract, a specific folder taxonomy, or a specific way of linking attachments, you will be adapting its output rather than generating it directly. The project's own structure reflects this: it ships a `demo/` folder with word cloud examples, a `docs/` directory, and a TOML config surface, so customization is expected to happen through configuration rather than through forking.

A second alternative is not converting at all and pointing a local search tool at the raw JSON. That works for search and fails for reading, because the JSON is a node graph. Convoviz's value is precisely that it resolves the graph into linear text.

Maintenance, licence and the cost of upgrading

Convoviz is MIT licensed, which is permissive and imposes no conditions on how you use the output. The licence file is at `LICENSE` in the repository, and `pyproject.toml` declares the same identifier. That matters less for the tool than for the Markdown it produces: your converted archive is your own data, and the licence does not restrict redistributing the converter or the files it writes.

The project is active. The last push was on 2026-09-13, and the most recent release listed is v0.7.6 on the same date, following v0.7.5 on 2026-09-08 and v0.7.4 on 2026-08-26. Releases are frequent enough that pinning a version is reasonable if you script the tool.

Upgrade cost is mostly configuration drift. The tool reads a TOML file with nested keys such as `conversation.markdown.show_timestamp` and `wordcloud.include_assistant_text`; if a key is renamed between versions, a config you wrote earlier can stop taking effect. The README's advice to generate a user config with `convoviz config init` is also the upgrade path: regenerate it and diff against your edited copy. The Python floor is 3.12, stated in `pyproject.toml` as `requires-python = ">=3.12"`, so an older interpreter is a hard blocker rather than a warning.

Editorial conclusion

Convoviz fits anyone who already keeps notes in Markdown and wants ChatGPT history to live in the same folder tree, and it fits anyone who wants a quick look at their own usage patterns. It is the wrong tool if you want incremental sync, a hosted archive, or a viewer that reads ChatGPT JSON without writing files. Before adopting it, run convoviz config init and read the generated config.toml, then do one export into a throwaway folder with --outputs markdown and confirm the filenames, frontmatter and media links match what your note-taking app expects.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mohamed-chs/convoviz on GitHub
4. README
5. Releases