Getting Started en

Getting Started

한국어 | English

1. Place the raw export

Drop the raw zip a vendor gave you as-is, without unzipping it into the location below (already-unzipped content also works).

data/
├── chatgpt/   # ChatGPT's Data export zip as-is, or its unzipped contents
├── gemini/    # Google Takeout zip as-is, or its unzipped contents
└── claude/    # Claude's (Anthropic) data export zip as-is, or its unzipped contents

If run.py can't find the files it needs in a vendor's folder, it automatically unzips any *.zip in that folder in place and looks again (common/zip_extract.py). If it's split into multiple part-zips like Google Takeout does, just drop them all in the same folder — they extract and merge naturally regardless of order. Original zip files are never deleted.

What real vendor exports actually look like (once unzipped)

• ChatGPT (the zip from "Settings → Data controls → Export"): usually not wrapped in a folder — conversations.json, chat.html, file_*.dat, etc. sit right at the top level of the archive. Depending on your unzip tool it may end up wrapped in one extra folder, but that's fine too since discovery is recursive.
• Gemini (the zip from Google Takeout with only "Gemini Apps" selected): always wrapped in at least one layer like Takeout/<service name>/, with My Activity.html and attached media files sitting side by side inside it. Just drop the whole Takeout/ folder into data/gemini/ (no need to dig into subfolders yourself).
• Claude (the zip from "Settings → Account → Export data"): the top level of the archive has conversations.json (all conversations that aren't attached to a project, as one array), design_chats/ (one file per conversation that is attached to a project), projects/ (project metadata, when present), and so on. If your account has a lot of data this can come split into multiple parts, e.g. data-...-batch-0000.zip — only a single part is supported right now. Extracting several parts into the same folder would make later parts silently overwrite the earlier parts' conversations.json/design_chats/, losing conversations, so if you have multiple parts you need to process each one separately.

2. Run it

python run.py

Only vendors whose presence is detected under data/ are automatically picked and run. To run a specific vendor only, pass --vendor chatgpt, --vendor gemini, or --vendor claude. Add --dry-run to print parsing results (session count, skip count, attachment resolve success/failure counts) to the console without creating any actual files.

If you don't want to move the raw export into data/<vendor>/ (e.g. you want to use a zip that's still sitting in your Downloads folder as-is), you can point directly at its location with --input — no real path is ever hardcoded anywhere in the code, and you can point at wherever you want on each run:

python run.py --vendor gemini --input "gemini=C:\Users\me\Downloads\takeout.zip"

Pass a folder and it's used as the source as-is (nothing is copied/moved); pass a .zip file and the original is left untouched while only its contents are extracted into data/<vendor>/.

3. Check the results

Results are generated under result/<vendor>/*.md (+ result/<vendor>/Attachments/). Claude is the exception: conversations attached to a project are generated under result/claude/<project name>/*.md, one subfolder per project, while conversations that aren't attached to a project go straight into result/claude/*.md like the other vendors.

4. Apply to your Obsidian vault

Once you've reviewed them, run with --publish to apply them to your actual Obsidian vault (see Configuration for path setup).

python run.py --publish

Conversion (step 2) and applying to the vault (step 4) are kept separate because writing to your real PKM store is hard to undo, so you get a chance to review result/ first.

Exit codes

• 0: Completed normally.
• 1: No vendor ran at all (nothing found under data/<vendor>/).
• 2: Some vendor only partially succeeded (e.g. one of several conversations-*.json files was corrupted and failed to parse) — check the [warning]/⚠️ logs in the console. If you're calling this pipeline from an automation script, make sure to check the exit code.

Requirements

The runtime pipeline itself uses only the standard library (Python 3.10+). No external packages needed. See Development for running the tests.