Cursor Sync · Перенос и синхронизация чатов Cursor

Краткое описание

Cursor Sync переносит чаты и данные проекта Cursor с одного профиля на другой: между аккаунтами Windows, папками %APPDATA%\Cursor, локальными профилями или компьютерами через bundle-папку.

Утилита состоит из пошагового GUI-мастера и командной строки. Для повседневной работы удобнее графический режим, для скриптов и точечных операций доступен CLI.

Важно:

• Перед импортом и синхронизацией закройте Cursor, иначе SQLite может быть заблокирован.
• На целевом профиле один раз откройте папку проекта в Cursor и закройте редактор, чтобы появилась запись в workspaceStorage.
• После любого импорта нужен полный перезапуск Cursor. Reload Window / Ctrl+R недостаточно.

Стек технологий

| Компонент | Версия / статус | Назначение |
|————|——————|————|
| Python | 3.10+ | CLI, файловые операции, SQLite, GUI |
| tkinter | входит в стандартную поставку Python на Windows | Пошаговый графический мастер |
| SQLite | через стандартный модуль sqlite3 | Чтение и запись локальных баз Cursor |
| Windows batch | cmd / .bat | Запуск GUI двойным кликом |

Внешних Python-зависимостей, сборки и упаковки сейчас нет.

Ключевые фичи

• Экспорт одного проекта Cursor в папку-bundle.
• Экспорт нескольких проектов в multi-bundle.
• Импорт single-bundle и multi-bundle в другой профиль Cursor.
• Прямая синхронизация между двумя профилями Cursor на одном компьютере без ручного bundle.
• Пошаговый GUI-мастер с режимами Экспорт, Импорт, Синхронизация.
• Preflight-проверки профиля Cursor, проекта, bundle, глобальной базы и процесса Cursor.exe.
• Чтение SQLite через снимок базы вместе с -wal и -shm.
• Резервные копии целевых SQLite-баз перед импортом.
• Режим --copy для повторного импорта с новыми UUID чатов.
• Копирование workspace-состояния, глобальных composer/chat записей и agent-transcripts.
• Исключение MCP-кэша mcps/ из переноса.

Что копируется:

| Данные | Где лежит на Windows |
|———|———————-|
| Список чатов Composer | %APPDATA%\Cursor\User\workspaceStorage\<id>\state.vscdb |
| Тексты сообщений | %APPDATA%\Cursor\User\globalStorage\state.vscdb -> cursorDiskKV |
| Agent transcripts | %USERPROFILE%\.cursor\projects\<slug>\agent-transcripts |

Не копируется: MCP-кэш (mcps/), настройки аккаунта, подписка, облачные данные Cursor.

Установка и запуск

Требования

• Python 3.10+.
• Windows для основного пользовательского сценария.
• Закрытый Cursor перед импортом и синхронизацией.

GUI

Windows: двойной клик по run_gui.bat.

Или из терминала:

cd "D:\WinProjects\@CursorSync"
python cursor_sync_gui.py

# то же самое:
python cursor_sync.py gui

В мастере слева отображаются шаги:

• ○ — еще не пройден.
• ● — текущий шаг.
• ✓ — выполнен.

Можно кликнуть по уже пройденному шагу в списке слева, чтобы вернуться и исправить данные.

CLI

# список проектов в текущем профиле
python cursor_sync.py list

# экспорт
python cursor_sync.py export "D:\Projects\MyApp" -o "D:\backup\myapp-cursor"

# импорт: проект на приемнике уже открывался в Cursor
python cursor_sync.py import "D:\backup\myapp-cursor" "D:\Projects\MyApp"

# прямой перенос между двумя папками Cursor
python cursor_sync.py sync "D:\Projects\MyApp" `
  --source "C:\Users\A\AppData\Roaming\Cursor" `
  --target "C:\Users\B\AppData\Roaming\Cursor"

# другой путь проекта на приемнике
python cursor_sync.py sync "D:\Old\MyApp" `
  --source "C:\Users\A\AppData\Roaming\Cursor" `
  --target "C:\Users\B\AppData\Roaming\Cursor" `
  --target-project "E:\Work\MyApp"

# повторный импорт без дублей: новые UUID чатов
python cursor_sync.py import "D:\backup\myapp-cursor" "D:\Projects\MyApp" --copy

Профили по умолчанию — %APPDATA%\Cursor текущего пользователя. Для другого аккаунта задайте --source / --target.

Типичный сценарий: два аккаунта Windows

На аккаунте A:

1. Закройте Cursor.
2. Запустите run_gui.bat -> Экспорт.
3. Укажите источник, обычно это %APPDATA%\Cursor.
4. Выберите проект и папку bundle, например D:\backup\myapp-cursor.
5. Пройдите проверки и нажмите Выполнить.

На аккаунте B:

1. Один раз откройте D:\Projects\MyApp в Cursor и закройте редактор.
2. Закройте Cursor.
3. GUI -> Импорт -> укажите D:\backup\myapp-cursor и профиль B (C:\Users\B\...\AppData\Roaming\Cursor).
4. Пройдите проверки, нажмите Выполнить и полностью перезапустите Cursor.

Скриншоты/GIF

Скриншоты и GIF сейчас не добавлены. GUI запускается локально через run_gui.bat или python cursor_sync_gui.py; основные экраны: выбор режима, выбор профиля, выбор проектов, preflight-проверки, выполнение и итог.

Roadmap

• Добавить автоматические smoke-тесты для list, export, import --copy и preflight-логики.
• Добавить скриншоты GUI-мастера в README.
• Добавить упаковку или простой релизный архив для Windows.
• Проверять совместимость после значимых обновлений Cursor, потому что официального API для локальных данных нет.
• При необходимости расширить документацию по восстановлению из .backup-* файлов.

Ссылки на /doc/

• `doc/ARCHITECTURE.md` — дерево проекта, архитектурные паттерны, схема данных и взаимодействие компонентов.
• `doc/CHANGELOG.md` — история изменений, категории Added / Changed / Fixed и технические заметки.
• `doc/AI_RULES.md` — стиль кода, ограничения и текущий контекст разработки.

Ограничения

• Официального API у Cursor нет — используются только локальные файлы.
• Глобальная БД на диске может быть очень большой; в bundle попадают только чаты выбранного проекта.
• Схема хранения Cursor меняется между версиями — после обновления редактора проверьте перенос на тестовом проекте.

Альтернатива

Расширение для Cursor с UI: Cursor Chat Transfer (на Windows для записи в БД нужен sqlite3 в PATH).

Cursor Sync — отдельная утилита, без установки в редактор, с пошаговым мастером и проверками.

История изменений

Все заметные изменения проекта фиксируются в этом файле.

Формат основан на Keep a Changelog. Проект пока не использует полноценное семантическое версионирование; текущий рабочий формат bundle имеет MANIFEST_VERSION = 1.

[Unreleased]

Added

• README приведен к строгому стандарту: заголовок и бейджи, краткое описание, стек технологий, ключевые фичи, установка и запуск, скриншоты/GIF, roadmap и ссылки на /doc/.
• doc/CHANGELOG.md приведен к структуре с блоками по версиям, категориями Added, Changed, Fixed и техническими заметками.
• doc/ARCHITECTURE.md дополнен деревом директорий, архитектурными паттернами, схемой данных и взаимодействием компонентов.
• doc/AI_RULES.md дополнен стилем кода, ограничениями и текущим контекстом разработки.

Changed

• Документация перераспределена строго по 4 файлам: README.md, doc/CHANGELOG.md, doc/ARCHITECTURE.md, doc/AI_RULES.md.
• Разделы про устройство bundle, SQLite-ключи, preflight-проверки и CLI/GUI оставлены в документации без изменения технического смысла.

Fixed

• Устранено дублирование между README и /doc/: README теперь описывает пользовательский быстрый старт, а подробности архитектуры и сопровождения вынесены в /doc/.

Technical Notes

• Старых документов за пределами стандарта не найдено: дополнительных TODO, NOTES, txt или старых changelog-файлов в проекте нет.
• Автоматические тесты не настроены, поэтому документационный рефакторинг проверяется чтением файлов и диагностикой Markdown в редакторе.

[0.1.0] — Current

Added

• CLI-утилита cursor_sync.py для команд list, export, import, sync и gui.
• Пошаговый GUI-мастер на tkinter для экспорта, импорта и прямой синхронизации.
• Windows-лаунчер run_gui.bat для запуска GUI двойным кликом.
• Экспорт одного проекта Cursor в папку-bundle.
• Экспорт нескольких проектов в подпапки output_dir/<slug>/ с корневым manifest.json типа multi.
• Импорт всех bundle из подпапок или multi-manifest в корне.
• Импорт single-bundle с обычным manifest.json.
• Прямая синхронизация source Cursor -> bundle -> target Cursor.
• Опция --keep-bundle для сохранения временного bundle при CLI-синхронизации.
• Опция --copy для безопасного повторного импорта с новыми UUID чатов.
• Preflight-проверки профиля Cursor, проекта, bundle, глобальной базы и процесса Cursor.exe.
• Чтение workspace и global SQLite через временный снимок с учетом файлов -wal и -shm.
• Копирование workspace-состояния, включая файлы workspace-папки, кроме *.backup и obsolete.
• Копирование agent-transcripts из .cursor/projects/<slug> без MCP-кэша mcps.
• Создание manifest.json с version, exported_at, source_folder, workspace_id, project_slug, composer_ids, composer_meta, workspace_items, global_chat.
• Резервные копии целевых SQLite-баз перед импортом в формате state.backup-YYYYMMDD-HHMMSS.vscdb.

Changed

• GUI использует функции из cursor_sync.py как тонкая оболочка и не дублирует бизнес-логику.
• При экспорте чтение допускается через снимок БД, даже если Cursor запущен, но это отображается как предупреждение.
• При импорте и синхронизации Cursor должен быть закрыт, потому что операция пишет в SQLite.
• При импорте глобальные записи пишутся через INSERT OR IGNORE, а список composer-чатов объединяется с текущими чатами проекта.

Fixed

• Повторный импорт может выполняться с --copy, чтобы создать копии чатов с новыми ID и снизить риск конфликтов с уже существующими записями.
• Перед записью целевых баз создаются резервные копии, чтобы оставить путь ручного восстановления после неудачного импорта.
• Для чтения БД копируются -wal и -shm, чтобы снимок был согласованнее при активной SQLite WAL-журнализации.

Technical Notes

• У Cursor нет стабильного публичного API для этих данных; проект работает с локальными файлами и внутренними SQLite-ключами Cursor.
• Глобальная база может быть большой, поэтому копирование снимка иногда занимает минуты.
• Схема хранения Cursor может измениться после обновления редактора; перенос нужно проверять на тестовом проекте.
• Автоматизированного тестового набора и отдельного шага сборки сейчас нет.