diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..7efe8a4 --- /dev/null +++ b/README.en.md @@ -0,0 +1,107 @@ +# declaude + +[Русский](https://github.com/EDeev/declaude/blob/main/README.md) · **English** + +[![CI](https://github.com/EDeev/declaude/actions/workflows/ci.yml/badge.svg)](https://github.com/EDeev/declaude/actions/workflows/ci.yml) +[![PyPI](https://img.shields.io/pypi/v/claude-export-html)](https://pypi.org/project/claude-export-html/) +[![Python](https://img.shields.io/pypi/pyversions/claude-export-html)](https://pypi.org/project/claude-export-html/) +[![License](https://img.shields.io/github/license/EDeev/declaude)](https://github.com/EDeev/declaude/blob/main/LICENSE) + +Turns a Claude.ai data export into a static HTML archive: browse, search and read all your chats and +projects in a browser, offline, with no servers or databases. + +**Status:** personal project, maintained · online version at [fe0.ru/declaude](https://fe0.ru/declaude/) + +![Archive home page](https://raw.githubusercontent.com/EDeev/declaude/main/docs/screenshots/index.png) + +**Stack:** Python 3.9+ (standard library only) · HTML · CSS · vanilla JS + +## Features + +- A page per chat and project, a home page with stats and recent chats +- Markdown: headings, lists, tables, quotes, code with highlighting (Python, JS/TS, SQL, Bash, Go, Rust) +- Search and filter across all chats, light and dark themes, Russian and English UI +- Assign chats to projects right in the browser and export `mapping.json` +- Incremental update from a new export: only changed chats are rebuilt +- Links from chats are safe: `javascript:` and similar schemes never reach the archive + +## Installation + +```bash +pipx install claude-export-html # or: pip install claude-export-html +``` + +Don't want to install anything? Upload the zip at [fe0.ru/declaude](https://fe0.ru/declaude/). If +privacy matters, run it locally. + +## Usage + +1. Claude.ai → **Settings → Privacy → Export data**, download the zip from the email and unpack it. +2. Build the archive and open `claude_archive/index.html`: + +```bash +declaude --build --source ./claude-export +declaude --build --source ./claude-export --output ./my-archive # custom folder +declaude --update new_export.zip # add a newer export +declaude --map && declaude --remap +``` + +| Option | Purpose | +|---|---| +| `--build` | full build from an unpacked export | +| `--source PATH` | export folder (default `claude-backup-v1`) | +| `--output PATH` | archive folder (default `claude_archive`) | +| `--update ZIP` | add data from a new zip, project assignments are kept | +| `--map CHAT PROJECT`, `--remap` | assign a chat to a project and rebuild the home and project pages | +| `--mapping PATH` | assignments file (default `./mapping.json`) | + +`python -m declaude` works as well as the `declaude` command. + +> [!NOTE] +> The archive is plain HTML files; no data is sent anywhere. Theme and language choices are stored in +> the browser's localStorage. + +## Screenshots + +| Chat | Project | +|---|---| +| ![Chat page](https://raw.githubusercontent.com/EDeev/declaude/main/docs/screenshots/conversation.png) | ![Project page](https://raw.githubusercontent.com/EDeev/declaude/main/docs/screenshots/project.png) | + +## Using from Python + +```python +from pathlib import Path +from declaude import DataLoader, MappingManager, SiteBuilder + +loader = DataLoader(Path("claude-export")); loader.load() +mapping = MappingManager(Path("mapping.json")); mapping.load() +SiteBuilder(Path("archive"), loader, mapping).build_all() +``` + +This is how the web version on fe0.ru uses it; FastAPI integration notes (in Russian): +[docs/fastapi-integration.md](https://github.com/EDeev/declaude/blob/main/docs/fastapi-integration.md). + +## Development + +```bash +pip install -e . -r requirements-dev.txt +ruff check . && pytest +``` + +The tests build an archive from a fictional export in `tests/fixtures` and check pages, Markdown, +escaping and link safety. CI runs them on Python 3.9–3.13; every `v*` tag publishes the package to PyPI. + +## License + +MIT — see [LICENSE](https://github.com/EDeev/declaude/blob/main/LICENSE). + +## Author + +**Egor Deev** — [GitHub](https://github.com/EDeev) · [Telegram](https://t.me/DeevEgor) · [egor@deev.space](mailto:egor@deev.space) + +--- + +
+ ⭐ If you find this project useful, give it a star on GitHub! +

Made with ❤️ — deev.space

+
diff --git a/README.md b/README.md index 92aff0d..42fb869 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,108 @@ # declaude -Автономная утилита для преобразования официального экспорта данных Claude.ai в интерактивный статический HTML-архив. +**Русский** · [English](README.en.md) -Позволяет локально хранить, просматривать и быстро искать диалоги без внешних зависимостей и необходимости поднимать базы данных или веб-серверы. +[![CI](https://github.com/EDeev/declaude/actions/workflows/ci.yml/badge.svg)](https://github.com/EDeev/declaude/actions/workflows/ci.yml) +[![PyPI](https://img.shields.io/pypi/v/claude-export-html)](https://pypi.org/project/claude-export-html/) +[![Python](https://img.shields.io/pypi/pyversions/claude-export-html)](https://pypi.org/project/claude-export-html/) +[![License](https://img.shields.io/github/license/EDeev/declaude)](LICENSE) -## Онлайн-версия +Превращает экспорт данных Claude.ai в статический HTML-архив: все чаты и проекты можно листать, +искать и читать в браузере без интернета, серверов и баз данных. -Не хочется устанавливать Python и разбираться руками — есть готовая веб-версия: -**https://fe0.ru/declaude/**. Загружаете zip-экспорт, получаете готовый архив — без установки -чего-либо. Если важна приватность данных, запустите скрипт локально по инструкции ниже. +**Статус:** личный проект, работает · онлайн-версия на [fe0.ru/declaude](https://fe0.ru/declaude/) + +![Главная страница архива](docs/screenshots/index.png) + +**Стек:** Python 3.9+ (только стандартная библиотека) · HTML · CSS · vanilla JS ## Возможности -- **Полная автономность:** генерирует чистые HTML-страницы для каждого диалога, которые открываются в любом браузере. -- **Страницы проектов:** рендеринг контекстных документов и шаблонов системных промптов для каждого проекта. -- **Полноценная поддержка Markdown:** заголовки, списки, таблицы, цитаты, блоки кода. -- **Подсветка синтаксиса без сторонних библиотек:** встроенная поддержка Python, JavaScript, TypeScript, SQL, Bash, Go и Rust. -- **Темы оформления и языки:** переключение между светлой и тёмной темой, а также интерфейс на русском и английском языках (выбор сохраняется в LocalStorage). -- **Маппинг проектов:** возможность связывать диалоги с проектами прямо в браузере с выгрузкой файла `mapping.json` и быстрой пересборкой. -- **Инкрементальные обновления:** режим `--update` обновляет только добавленные или изменённые диалоги. -- **Нулевые зависимости:** работает исключительно на стандартной библиотеке Python 3.8+. +- Отдельная страница на каждый чат и проект, главная со статистикой и последними чатами +- Markdown: заголовки, списки, таблицы, цитаты, код с подсветкой (Python, JS/TS, SQL, Bash, Go, Rust) +- Поиск и фильтр по всем чатам, светлая и тёмная тема, интерфейс на русском и английском +- Привязка чатов к проектам прямо в браузере с выгрузкой `mapping.json` +- Инкрементальное обновление из нового экспорта: пересобираются только изменённые чаты +- Ссылки из чатов безопасны: `javascript:` и подобные схемы не попадают в архив -## Подготовка данных +## Установка -1. Откройте **claude.ai → Settings → Privacy → Export data**. -2. Дождитесь письма со ссылкой и скачайте zip-архив с выгрузкой. -3. Распакуйте архив в отдельную папку. Внутри находятся файлы `conversations.json`, `users.json` и каталог `projects/`. +```bash +pipx install claude-export-html # или: pip install claude-export-html +``` + +Не хочется ничего ставить — загрузите zip на [fe0.ru/declaude](https://fe0.ru/declaude/). Если важна +приватность, запускайте локально. ## Использование -### Первая сборка архива +1. Claude.ai → **Settings → Privacy → Export data**, скачайте zip из письма и распакуйте. +2. Соберите архив и откройте `claude_archive/index.html`: ```bash -python declaude.py --build --source ./claude-export +declaude --build --source ./claude-export +declaude --build --source ./claude-export --output ./my-archive # своя папка +declaude --update new_export.zip # добавить новый экспорт +declaude --map && declaude --remap ``` -После завершения откройте файл `claude_archive/index.html` в браузере. +| Параметр | Назначение | +|---|---| +| `--build` | полная сборка из распакованного экспорта | +| `--source ПУТЬ` | папка с экспортом (по умолчанию `claude-backup-v1`) | +| `--output ПУТЬ` | куда сложить архив (по умолчанию `claude_archive`) | +| `--update ZIP` | добавить данные из нового zip, привязки к проектам сохраняются | +| `--map ЧАТ ПРОЕКТ`, `--remap` | привязать чат к проекту и пересобрать главную и проекты | +| `--mapping ПУТЬ` | файл привязок (по умолчанию `./mapping.json`) | -### Указание своей папки для архива +Вместо команды `declaude` можно запускать `python -m declaude`. + +> [!NOTE] +> Архив — обычные HTML-файлы, данные никуда не отправляются. Выбор темы и языка хранится в +> localStorage браузера. + +## Как выглядит + +| Чат | Проект | +|---|---| +| ![Страница чата](docs/screenshots/conversation.png) | ![Страница проекта](docs/screenshots/project.png) | + +## Использование из Python + +```python +from pathlib import Path +from declaude import DataLoader, MappingManager, SiteBuilder + +loader = DataLoader(Path("claude-export")); loader.load() +mapping = MappingManager(Path("mapping.json")); mapping.load() +SiteBuilder(Path("archive"), loader, mapping).build_all() +``` + +Так библиотека встроена в веб-версию на fe0.ru — заметки об интеграции в FastAPI: +[docs/fastapi-integration.md](docs/fastapi-integration.md). + +## Разработка ```bash -python declaude.py --build --source ./claude-export --output ./my-archive +pip install -e . -r requirements-dev.txt +ruff check . && pytest ``` -### Инкрементальное обновление из нового архива - -```bash -python declaude.py --update new_export.zip -``` - -Регенерируются только новые и отредактированные страницы, текущая привязка диалогов к проектам в `mapping.json` сохраняется. - -### Назначение диалога проекту через консоль - -```bash -python declaude.py --map -python declaude.py --remap -``` - -Быстрая пересборка страниц проектов (`--remap`) занимает секунды, так как не пересобирает неизменённые диалоги. - -## Структура сгенерированного архива - -``` -claude_archive/ -├── index.html # Главная страница: статистика, проекты, последние чаты -├── all_conversations.html # Полный список диалогов с поиском и фильтрацией -├── conversations/ -│ └── .html # Страницы отдельных диалогов -├── projects/ -│ └── / -│ └── index.html # Страницы проектов с документами и диалогами -└── assets/ - ├── style.css - └── app.js -``` - -## Параметры командной строки - -- `--build` — полная сборка архива из исходного каталога. -- `--source ПУТЬ` — путь к каталогу с распакованным экспортом (по умолчанию: `claude-backup-v1`). -- `--output ПУТЬ` — каталог для сохранения HTML-архива (по умолчанию: `claude_archive`). -- `--update АРХИВ.ZIP` — добавление данных из нового zip-архива с сохранением маппинга. -- `--remap` — быстрая пересборка индексной страницы и страниц проектов. -- `--map CONV_ID PROJ_ID` — ручное сопоставление диалога с проектом. -- `--mapping ПУТЬ` — путь к файлу сопоставлений (по умолчанию: `./mapping.json`). +Тесты собирают архив из вымышленного экспорта в `tests/fixtures` и проверяют страницы, Markdown, +экранирование и защиту ссылок. CI гоняет их на Python 3.9–3.13; на каждый тег `v*` пакет публикуется +на PyPI. ## Лицензия -MIT +MIT — см. [LICENSE](LICENSE). + +## Автор + +**Деев Егор Викторович** — [GitHub](https://github.com/EDeev) · [Telegram](https://t.me/DeevEgor) · [egor@deev.space](mailto:egor@deev.space) + +--- + +
+ ⭐ Если проект оказался полезным, поставьте звёздочку на GitHub! +

Сделано с ❤️ — deev.space

+
diff --git a/docs/screenshots/conversation.png b/docs/screenshots/conversation.png new file mode 100644 index 0000000..11e86d1 Binary files /dev/null and b/docs/screenshots/conversation.png differ diff --git a/docs/screenshots/index.png b/docs/screenshots/index.png new file mode 100644 index 0000000..b710a3e Binary files /dev/null and b/docs/screenshots/index.png differ diff --git a/docs/screenshots/project.png b/docs/screenshots/project.png new file mode 100644 index 0000000..8208a9d Binary files /dev/null and b/docs/screenshots/project.png differ