Chat History

Browse and export your ChatGPT and Claude conversations locally.

Getting Started

Requires Python 3.11+ and uv.

1. Export your chats from ChatGPT or Claude (Settings → Export data). Both services send a ZIP file by email.

2. Create a folder for your chat history, save the ZIP there, and open a terminal in that folder. The wizard will store all data inside it.

3. Run the setup wizard:

   hljs language-bash

   Copy

   uvx chat-history
   

   The wizard finds your export files, configures everything, and opens the browser.

Next time, run uvx chat-history in the same folder to start browsing. To update to the latest version, run uvx chat-history install.

To export all conversations as markdown (useful for feeding to other AI tools):

uvx chat-history export

Features

• Unified conversation browser for ChatGPT and Claude exports
• Provider-aware favorites and external links
• Full-text search with optional semantic search (OpenAI embeddings + FAISS)
• Activity and token statistics
• Export conversations to markdown for downstream AI workflows

CLI Reference

All commands work as uvx chat-history <command> or, if installed locally, chat-history <command>.

serve

uvx chat-history serve [--host 127.0.0.1] [--port 8080] [--no-browser]

export

uvx chat-history export [--provider chatgpt|claude|all] [--out DIR] [--clean]
                        [--exclude-system] [--exclude-tool]
                        [--exclude-thinking] [--exclude-attachments]

• --clean removes old export files before writing (scoped to --provider if set)
• Default output: ./data/export/{chatgpt|claude}/

init

uvx chat-history init [--path DIR]

Scans the current folder and ~/Downloads for export ZIPs, validates them, extracts to ./data/, writes ./data/.env, and offers to start the server. Supports adding a second provider to an existing setup.

Configuration

All config lives in ./data/.env (created by the wizard or manually):

Developer Setup

make install    # uv sync
make dev        # uvicorn with hot-reload on :8080
make test       # run tests

Install as a global command from the local repo (editable, changes reflected immediately):

make tool-install         # uv tool install -e .
chat-history              # works from any directory
make tool-uninstall       # uv tool uninstall chat-history

Notes

• Export is non-destructive by default. Existing files remain unless --clean is used.
• Token stats for Claude are approximate (fallback tokenizer), not exact Claude-native counts.