Skip to content

Chumikov/opencode-sync

BranchesTags

Repository files navigation

opencode-sync

Синхронизация сессий OpenCode между вашими устройствами через приватный git-репозиторий.

Начинайте сейссию работы с OpenCode с одного устройства, а продолжайте на другом. Даже еслиу вас одно устройство - просто синхронизируйте свои сессии, чтобы не потерять их. Opencode-sync экспортирует сессии OpenCode в JSON-файлы, хранит их в вашем приватном git-репозитории. Каждое устройство push'ит свои сессии и pull'ит с других.

Возможности

  • Проектная область видимости — push/pull синхронизируют только сессии текущего проекта (определяется по git-репозиторию)
  • Автосинхронизация — shell-функция opencode() автоматически синхронизирует перед/после работы
  • Manifest-based удаление — сессия удаляется когда все устройства её удалили
  • Deleted set — удалённые локально сессии не возвращаются при pull
  • Защита первого запуска — при первой синхронизации локальные сессии не удаляются
  • Preflight-проверки — перед каждой операцией проверяется интернет, доступ к GitHub, наличие OpenCode
  • TUI-setup — интерактивный мастер настройки с валидацией доступа к репозиторию
  • Нативные команды OpenCode — все операции производятся через CLI OpenCode (db, export, import, session delete)

Требования

Зависимость Минимальная версия
Node.js >= 20
git любой
opencode >= 1.14
PAT-токен или SSH-ключ для доступа к GitHub

Почему opencode ≥ 1.14? Начиная с версии 1.14, OpenCode хранит сессии в SQLite и поддерживает команду opencode db, которая необходима для экспорта всех сессий (а не только текущего проекта). При opencode-sync setup версия проверяется автоматически.

Установка

Из npm:

npm install -g @chumikov/opencode-sync

Из исходников:

git clone https://github.com/Chumikov/opencode-sync.git
cd opencode-sync
npm install && npm run build
npm link

Настройка

Шаг 1: Создать приватный репозиторий на GitHub

Important

Репозиторий рекомендую обязательно сделать приватным. Файлы ваших сессий в OpenCode могут содержать промпты, фрагменты кода и результаты работы.

  1. Откройте github.com/new
  2. Repository name — любое, например opencode-sessions
  3. Visibility — Private
  4. Не добавляйте README, .gitignore или license (пустой репозиторий)
  5. Нажмите Create repository

Шаг 2: Настроить доступ к GitHub

Вариант A: Personal Access Token (рекомендуется)

Токен достаточно создать один раз и использовать на всех устройствах — не нужно переносить SSH-ключи.

  1. GitHub → Settings → Developer settings → Personal access tokens → Generate new token (classic)
  2. Выберите scope repo (полный доступ к приватным репозиториям)
  3. Скопируйте токен
  4. URL для setup: https://<TOKEN>@github.com/YOUR_USERNAME/<opencode-sessions>.git

Вариант B: SSH-ключ

Потребуется настроить SSH-ключ на каждом устройстве.

Проверьте, настроен ли ключ:

ssh -T git@github.com
# Hi username! You've successfully authenticated — ключ работает

Если Permission denied — сгенерируйте и добавьте ключ:

# Генерация ключа
ssh-keygen -t ed25519 -C "your-email@example.com"

# Копирование публичного ключа
cat ~/.ssh/id_ed25519.pub

# Добавьте ключ на GitHub: Settings → SSH and GPG keys → New SSH key
# Вставьте содержимое ~/.ssh/id_ed25519.pub

URL для setup: git@github.com:YOUR_USERNAME/<opencode-sessions>.git

Шаг 3: Запустить opencode-sync setup

opencode-sync setup

Интерактивный мастер:

  1. Проверяет OpenCode — если не установлен, процесс дальше не пойдёт
  2. Запрашивает URL репозитория — HTTPS с токеном или SSH
  3. Проверяет доступ — если доступа нет, покажет конкретную ошибку и подсказку:
    • Нет интернета → проверьте подключение
    • Нет SSH-доступа → инструкция по генерации ключа
    • Репозиторий не найден → проверьте URL
    • Ошибка аутентификации → инструкция по токену/SSH
  4. Предлагает повторить или изменить URL при ошибке
  5. Запрашивает имя устройства — будет видно в коммитах (по умолчанию — hostname)
  6. Клонирует репозиторий, определяет ветку
  7. Настраивает автосинхронизацию — добавляет shell-функцию (bash, zsh, fish или PowerShell)

Конфигурация сохраняется в ~/.config/opencode/sync.json.

Шаг 4: Перезапустить shell

Linux / macOS:

source ~/.zshrc   # или source ~/.bashrc

Windows (PowerShell):

. $PROFILE

fish:

# Функция загрузится автоматически при следующем запуске fish

Автосинхронизация

При setup автоматически определяется ваш shell и добавляется функция-обёртка для OpenCode.

Поддерживаемые shell

Shell Файл ОС
bash ~/.bashrc или ~/.bash_profile Linux, macOS
zsh ~/.zshrc macOS (default), Linux
fish ~/.config/fish/functions/opencode.fish Linux, macOS
PowerShell Documents/PowerShell/Microsoft.PowerShell_profile.ps1 Windows, Linux, macOS

Как это работает

bash / zsh:

opencode() {
  local _sync_log="$HOME/.local/share/opencode-sync/sync.log"
  mkdir -p "$(dirname "$_sync_log")" 2>/dev/null
  command opencode-sync pull 2>>"$_sync_log" || echo "opencode-sync: ошибка pull (подробности: $_sync_log)" >&2
  command opencode "$@"
  local exit_code=$?
  command opencode-sync push 2>>"$_sync_log" || echo "opencode-sync: ошибка push (подробности: $_sync_log)" >&2
  return $exit_code
}

При каждом запуске OpenCode:

  1. Pull — подтягивает сессии с других устройств
  2. OpenCode — запускается как обычно
  3. Push — отправляет ваши сессии в репозиторий

Ошибки записываются в ~/.local/share/opencode-sync/sync.log. При ошибке показывается краткое сообщение со ссылкой на лог-файл.

Команды

opencode-sync setup              # Первичная настройка (TUI)
opencode-sync push               # Экспортировать сессии в git
opencode-sync pull               # Импортировать сессии из git
opencode-sync sync               # Полный цикл: pull + push
opencode-sync status             # Конфигурация + проверка доступа к remote
opencode-sync push --dry-run     # Показать что будет отправлено, без изменений
opencode-sync pull --dry-run     # Показать что будет импортировано, без изменений

Как работает синхронизация

Область видимости (scope)

Push и pull фильтруют сессии по текущему проекту:

  • Из папки git-репозитория → синхронизируются только сессии этого проекта. Project ID определяется как SHA-1 первого коммита git-репозитория.
  • Из папки без git → синхронизируются только глобальные сессии (project_id = "global").
  • Первый push (манифест устройства ещё не создан) → экспортируются все сессии без фильтрации.

Каждое устройство записывает в git манифест — список всех своих текущих сессий (manifests/{device}.json). Манифест всегда содержит полный список (не только scoped-сессии) — это нужно для корректного удаления.

Push

  1. Проверяет интернет и доступ к репозиторию (preflight)
  2. Определяет scope по текущей директории (git root → первый коммит = project ID)
  3. Получает все сессии через opencode db, фильтрует по scope
  4. Экспортирует новые/изменённые сессии через opencode export
  5. Сохраняет JSON-файлы в sessions/{project_id}/{session_id}.json
  6. Сравнивает старый и новый манифест — удалённые id записываются в deleted set (manifests/{device}-deleted.json)
  7. Записывает полный манифест устройства
  8. Удаляет orphan-файлы в scoped-папке (сессии, которых нет ни в одном манифесте)
  9. Push в git

Pull

  1. Проверяет интернет и доступ к репозиторию (preflight)
  2. Pull из git
  3. Сканирует только sessions/{project_id}/ (или sessions/global/)
  4. Пропускает сессии из deleted set — они не возвращаются после локального удаления
  5. Импортирует новые/обновлённые сессии через opencode import
  6. Если манифест устройства существует в репо — удаляет локальные сессии, которые удалены на всех устройствах (через opencode session delete) и добавляет их в deleted set
  7. Если манифест устройства не существует (первая синхронизация) — шаг удаления пропускается

Удаление сессий

  1. Пользователь удаляет сессию на устройстве А
  2. Push на А: id сессии исчезает из манифеста А, добавляется в deleted set А
  3. Если id нет ни в одном манифесте — JSON-файл удаляется из git
  4. Pull на Б: если id нет в global alive set — сессия удаляется из локальной БД opencode, id добавляется в deleted set Б
  5. Сессия из deleted set не вернётся при следующем pull

Сессия удаляется с устройства только когда все устройства синхронизировались без неё.

Переменные окружения

Приоритет выше файла конфигурации.

Переменная Описание
OPENCODE_SYNC_REPO URL git-репозитория
OPENCODE_SYNC_DEVICE Имя устройства
OPENCODE_SYNC_PATH Локальный путь к клону
OPENCODE_SYNC_BRANCH Ветка в sync-репозитории
OPENCODE_BIN Путь к бинарнику opencode
OPENCODE_DB Путь к SQLite БД opencode

Добавление нового устройства

  1. Установите OpenCode и opencode-sync
  2. opencode-sync setup — укажите тот же URL репозитория (токен одинаковый для всех устройств)
  3. Готово — сессии автоматически синхронизируются при запуске opencode

Безопасность

  • Репозиторий обязательно приватный — файлы содержат промпты и фрагменты кода
  • Все операции через нативные команды OpenCode CLI
  • На Windows используется cmd /c для совместимости с .cmd/.exe shim'ами
  • URL маскируется в логах и сообщениях об ошибках
  • Preflight-проверки перед каждой операцией — понятные ошибки вместо сырого git stderr
  • Ошибки синхронизации записываются в ~/.local/share/opencode-sync/sync.log

Структура данных

sync-repo/
├── sessions/
│   ├── global/
│   │   └── {session_id}.json         # глобальные сессии
│   ├── e89b5fab.../
│   │   └── {session_id}.json         # сессии проекта (project_id = SHA первого коммита)
│   └── 3129bae8.../
│       └── {session_id}.json         # сессии другого проекта
├── manifests/
│   ├── laptop.json                   # манифест "laptop" (все живые id)
│   ├── laptop-deleted.json           # deleted set "laptop" (удалённые id)
│   ├── desktop.json                  # манифест "desktop"
│   └── desktop-deleted.json          # deleted set "desktop"
└── .gitignore

Chumikov Sec

About

Git-based session synchronization for opencode across devices

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 13

v1.2.7 Latest
May 1, 2026
+ 12 releases

Packages

 
 
 

Contributors

Languages