Jesse.Markowitz/ai-chatexport
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated to run on Windows and add est capabilities

Browse Source
This commit is contained in:
JesseMarkowitz
2026-03-30 11:08:05 -04:00
parent 304cf4fde4
commit 050cd49124
13 changed files with 524 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
README.md
View File

@@ -28,6 +28,8 @@ This tool is designed for a single user backing up their own conversations. Do n
## Installation
### Linux / macOS
```bash
git clone <repo-url>
cd ai-chat-exporter
@@ -36,6 +38,37 @@ source .venv/bin/activate
pip install -e ".[dev]"
```
### Windows
No admin access required. Run these in **Command Prompt** (`cmd.exe`) — it's the simplest option on Windows because it doesn't have PowerShell's script execution policy restrictions.
```bat
git clone <repo-url>
cd ai-chat-exporter
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
```
All `ai-chat-exporter` commands work identically in Command Prompt.
**Using PowerShell instead?** If you prefer PowerShell, you may need to allow script execution first (one-time, current user only):
```powershell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```
Then activate the venv and run commands the same way.
**Prerequisites:**
- Python 3.11 or later — install from [python.org](https://www.python.org/downloads/windows/). During installation, tick **"Add Python to PATH"**.
- Git — install from [git-scm.com](https://git-scm.com/) if not already present.
**Notes:**
- The cache manifest and logs are stored in `cache\` inside the install directory — the same as on Linux.
- File permission hardening (`chmod 600`) is silently ignored on Windows — not a concern for single-user desktop use.
- Joplin Web Clipper runs on `localhost:41184` on all platforms; no configuration changes needed.
---
## First Run: Run Doctor
@@ -43,7 +76,7 @@ pip install -e ".[dev]"
Before anything else, validate your setup:
```bash
python -m src.main doctor
ai-chat-exporter doctor
```
This checks token presence, format, expiry, directory permissions, disk space, and live API connectivity. Fix any failures before proceeding.
@@ -76,7 +109,7 @@ Session tokens are how your browser stays logged in. This tool uses them to acce
### When Tokens Expire
When a token expires you'll see a `401 Unauthorized` error. To refresh:
- Re-run the `auth` wizard: `python -m src.main auth`
- Re-run the `auth` wizard: `ai-chat-exporter auth`
- Or manually update the value in your `.env` file
---
@@ -86,7 +119,7 @@ When a token expires you'll see a `401 Unauthorized` error. To refresh:
The easiest way to configure tokens is the interactive wizard:
```bash
python -m src.main auth
ai-chat-exporter auth
```
This walks you through finding your token, validates it, shows the expiry date (ChatGPT only), and offers to write it to your `.env` automatically. Tokens are never echoed to the terminal.
@@ -128,8 +161,8 @@ cp .env.example .env
| Variable | Default | Description |
|----------|---------|-------------|
| `CACHE_DIR` | `~/.ai-chat-exporter` | Where to store the sync manifest |
| `LOG_FILE` | `~/.ai-chat-exporter/logs/exporter.log` | Log file path (`none` to disable) |
| `CACHE_DIR` | `./cache` | Where to store the sync manifest |
| `LOG_FILE` | `./cache/logs/exporter.log` | Log file path (`none` to disable) |
---
@@ -218,7 +251,7 @@ Each provider+project combination maps to a flat Joplin notebook created automat
### `auth` — Interactive token setup
```bash
python -m src.main auth
ai-chat-exporter auth
```
Guided wizard to find and save session tokens and ChatGPT project IDs. Detects OS and shows the correct DevTools shortcut.
@@ -226,7 +259,7 @@ Guided wizard to find and save session tokens and ChatGPT project IDs. Detects O
### `doctor` — Health check
```bash
python -m src.main doctor
ai-chat-exporter doctor
```
Checks: token presence, JWT validity and expiry, directory permissions, disk space, live API reachability. Exits with code 0 if all pass, 1 if any fail.
@@ -235,31 +268,31 @@ Checks: token presence, JWT validity and expiry, directory permissions, disk spa
```bash
# Export everything (new/updated only)
python -m src.main export
ai-chat-exporter export
# Single provider
python -m src.main export --provider claude
ai-chat-exporter export --provider claude
# JSON output
python -m src.main export --format json
ai-chat-exporter export --format json
# Both Markdown and JSON
python -m src.main export --format both
ai-chat-exporter export --format both
# Only conversations updated since a date
python -m src.main export --since 2024-06-01
ai-chat-exporter export --since 2024-06-01
# Only conversations in a specific project (case-insensitive substring)
python -m src.main export --project "learning python"
ai-chat-exporter export --project "learning python"
# Only conversations outside any project
python -m src.main export --project none
ai-chat-exporter export --project none
# Write to a custom directory
python -m src.main export --output /path/to/my/notes
ai-chat-exporter export --output /path/to/my/notes
# Preview without writing anything
python -m src.main export --dry-run
ai-chat-exporter export --dry-run
```
Options: `--provider [chatgpt|claude|all]`, `--format [markdown|json|both]`, `--output PATH`, `--since YYYY-MM-DD`, `--project NAME`, `--dry-run`
@@ -268,16 +301,16 @@ Options: `--provider [chatgpt|claude|all]`, `--format [markdown|json|both]`, `--
```bash
# List all conversations for all providers
python -m src.main list
ai-chat-exporter list
# Single provider
python -m src.main list --provider chatgpt
ai-chat-exporter list --provider chatgpt
# Filter by project
python -m src.main list --project "learning python"
ai-chat-exporter list --project "learning python"
# Only conversations outside any project
python -m src.main list --project none
ai-chat-exporter list --project none
```
Fetches and displays all conversations without exporting them. Useful for verifying what the tool can see before running an export.
@@ -286,19 +319,19 @@ Fetches and displays all conversations without exporting them. Useful for verify
```bash
# Sync all pending conversations to Joplin
python -m src.main joplin
ai-chat-exporter joplin
# Preview what would be synced without sending anything
python -m src.main joplin --dry-run
ai-chat-exporter joplin --dry-run
# Sync a single provider
python -m src.main joplin --provider chatgpt
ai-chat-exporter joplin --provider chatgpt
# Sync only conversations in a specific project
python -m src.main joplin --project "learning python"
ai-chat-exporter joplin --project "learning python"
# Sync only conversations outside any project
python -m src.main joplin --project none
ai-chat-exporter joplin --project none
```
Reads the local export cache and pushes each exported Markdown file to Joplin as a note. Notebooks are created automatically. Re-running is safe — notes are updated (not duplicated).
@@ -315,20 +348,20 @@ Options: `--provider [chatgpt|claude|all]`, `--project NAME`, `--dry-run`
```bash
# Show statistics
python -m src.main cache --show
ai-chat-exporter cache --show
# Clear all cached entries (forces full re-export next run)
python -m src.main cache --clear
ai-chat-exporter cache --clear
# Clear a single provider
python -m src.main cache --clear --provider claude
ai-chat-exporter cache --clear --provider claude
```
---
## How the Cache Works
The cache manifest lives at `~/.ai-chat-exporter/manifest.json` and records every exported conversation: its title, project, `updated_at` timestamp, output file path, and (after Joplin sync) the Joplin note ID.
The cache manifest lives at `cache/manifest.json` (inside the install directory) and records every exported conversation: its title, project, `updated_at` timestamp, output file path, and (after Joplin sync) the Joplin note ID.
On every `export` run:
1. Fetch the full conversation list from the provider
@@ -343,7 +376,7 @@ On every `joplin` run:
**This design makes every run inherently resumable.** If the tool is interrupted for any reason — rate limit, network drop, Ctrl+C, crash — simply re-run the same command. It will skip already-processed conversations and continue from where it stopped.
To force a full re-export: `python -m src.main cache --clear` then re-run export.
To force a full re-export: `ai-chat-exporter cache --clear` then re-run export.
---
@@ -351,7 +384,7 @@ To force a full re-export: `python -m src.main cache --clear` then re-run export
### `401 Unauthorized`
Your session token has expired.
- Run `python -m src.main auth` to get a new token interactively
- Run `ai-chat-exporter auth` to get a new token interactively
- Or manually copy a fresh cookie value into your `.env` file
Note: Claude's `sessionKey` is an opaque string — the only way to know it's expired is the 401 error. ChatGPT JWTs have an `exp` claim that the `doctor` command can decode and display.
@@ -391,10 +424,10 @@ The provider's internal API may have changed. Run with `--debug`, sanitize the o
Images, code interpreter outputs, DALL-E generations, and Claude artifacts are not exported in v0.2.0. A WARNING is logged for each skipped item. See `FUTURE.md` for the roadmap.
### Empty export / all conversations skipped
No new or updated conversations since your last run. To verify: `python -m src.main cache --show`. To force a full re-export: `python -m src.main cache --clear`.
No new or updated conversations since your last run. To verify: `ai-chat-exporter cache --show`. To force a full re-export: `ai-chat-exporter cache --clear`.
### Filing a bug report
1. Run with `--debug`: `python -m src.main export --debug 2>&1 | tee debug.log`
1. Run with `--debug`: `ai-chat-exporter export --debug 2>&1 | tee debug.log`
2. Remove any personal conversation content from `debug.log`
3. Open a GitHub Issue with the sanitized log and the exact command you ran