Gemini Exporter

A robust, local Python tool to automate the extraction and backup of your personal Google Gemini chat history.

Built because Google Takeout is historically unreliable, and trusting third-party browser extensions with your private chat data is a massive security risk. This script acts as a puppeteer for your existing web browser, meaning it relies on your active, authenticated session—bypassing captchas, bot detection, and login hurdles completely.

Goals

• Complete Data Ownership: Extract your conversations directly from the DOM and save them locally.
• Fidelity: Preserve the chats in multiple formats simultaneously (structured JSON, visually clean HTML, and semantic Markdown) so you can confidently delete them from Google's servers.
• Idempotency: Run the script repeatedly. It will check the local filesystem and skip conversations it has already downloaded, making it resilient to crashes or rate limits.

Abilities

• Live CDP Connection: Connects to your live Chrome session via the Chrome DevTools Protocol (CDP).
• Automated Scrolling: Automatically scrolls the history sidebar to discover all chats, and scrolls up inside each conversation to ensure the full history is loaded before extraction.
• Smart Extraction & Cleanup: Purges unnecessary UI elements (like follow-up buttons, elicitations, screen reader labels) before saving to ensure clean data.
• Format Generation: Automatically generates a structured JSON file, a readable Markdown file, and a self-contained styled HTML file for every conversation.
• Canvas Mode Recovery: Detects if Gemini opens a chat in full-screen "Canvas" mode and automatically restores the sidebar to continue scraping seamlessly.
• Whitelist Filtering: Includes a configurable TITLE_WHITELIST in main.py to only extract chats matching specific keywords.

Setup

Requires Python 3.13+.

1. Clone the repository and navigate into it.
2. Install the project dependencies:

   uv sync

3. Install the Playwright browser binaries:

   uv run playwright install chromium

Usage

To use this script, you must launch Google Chrome with remote debugging enabled so Playwright can attach to it.

Step 1: Fully Close Chrome

Ensure all instances of Google Chrome are closed. If Chrome is running in the background, the remote debugging flag will be silently ignored.

Step 2: Launch Chrome with Remote Debugging

Open your terminal and launch Chrome using the command for your operating system:

macOS:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile

Windows:

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\tmp\chrome-profile"

(Note: Your installation path may vary slightly, e.g., Program Files (x86))

Linux:

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile

Step 3: Log In to Gemini

In the new Chrome window that opens, navigate to gemini.google.com and ensure you are logged in.

Step 4: Run the Scraper

Leave the Chrome window open and run the extraction script:

uv run python main.py

The script will connect to the browser, traverse your chat history, extract the messages, and dump the structured data into a local conversations/ directory.

Output Format

Each conversation is saved in a dedicated directory inside the conversations/ folder, named after the sanitized chat title.

Inside each directory, you will find three files:

1. chat.json: A structured representation of the conversation, containing the exact message text and roles.
2. chat.md: A semantic Markdown file, utilizing markdownify to intelligently parse Gemini's custom web components into standard Markdown, preserving code blocks perfectly.
3. chat.html: A clean, self-contained HTML file. The script injects custom, readable CSS so you can open this file in any browser and view the chat beautifully styled, without relying on Google's external stylesheets.

Example structure:

conversations/
└── My_Awesome_Chat/
    ├── chat.json
    ├── chat.md
    └── chat.html

chat.json format:

{
  "title": "My Awesome Chat",
  "message_count": 2,
  "messages": [
    {
      "role": "user",
      "text": "Write a python script..."
    },
    {
      "role": "model",
      "text": "Here is the script..."
    }
  ]
}