main/PI-BACKUP-README.md

Бэкап среды Pi Coding Agent

Файлы рядом:

• pi-env-backup.sh — скрипт создания, проверки и восстановления бэкапа;
• PI-BACKUP-README.md — эта инструкция.

Скрипт переносит именно среду Pi, а не проекты.

Что сохраняется

• ~/.pi/agent/settings.json — глобальные настройки Pi;
• ~/.pi/agent/auth.json — авторизация и API-ключи;
• ~/.pi/agent/mcp.json и ~/.pi/agent/mcp-oauth/ — MCP;
• ~/.pi/agent/models.json, models.yml — настройки моделей;
• ~/.pi/agent/extensions/, skills/, npm/, git/ — плагины и Pi packages;
• ~/.pi/agent/AGENTS.md, keybindings.json, trust.json;
• ~/.pi/agent/sessions/ — история сессий (по умолчанию не сохраняется);
• ~/.pi/agent/pi-hermes-memory/ и projects-memory/ — память;
• ~/.pi/context-mode/ — индексы и локальные данные context-mode (по умолчанию не сохраняются);
• ~/.pi/agent/ayu/checkpoints/ — checkpoints (по умолчанию не сохраняются);
• ~/.agents/ — дополнительные пользовательские skills;
• ~/.pi/local-docs/, если каталог существует.

Архив также содержит манифест версий установленных программ и копию самого скрипта для восстановления.

Внимание: архив содержит секреты из auth.json, MCP OAuth и других конфигов. Не выкладывай его в публичное хранилище.

---

1. Создать полный бэкап

Закрой все запущенные Pi:

pkill -f pi-coding-agent || true

Создай каталог для архивов и запусти:

mkdir -p ~/pi-backups
cd /home/smog/main
./pi-env-backup.sh backup ~/pi-backups

Или сразу на внешний диск:

./pi-env-backup.sh backup /media/smog/SSD

На выходе будут два файла:

pi-backup-YYYYMMDD-HHMMSS.tar.zst
pi-backup-YYYYMMDD-HHMMSS.tar.zst.sha256

По умолчанию архив НЕ включает ayu/checkpoints, историю Pi-сессий и context-mode: это кэш/история, не нужные для работы плагинов. Поэтому архив обычно будет порядка 0.8–1 ГБ до сжатия и ориентировочно 0.4–0.8 ГБ после zstd. Точный размер скрипт покажет в конце.

---

2. Проверить архив

Посмотреть содержимое:

./pi-env-backup.sh list ~/pi-backups/pi-backup-*.tar.zst

Проверить контрольную сумму:

sha256sum -c ~/pi-backups/pi-backup-*.tar.zst.sha256

---

3. Дополнительные варианты бэкапа

По умолчанию уже создаётся облегчённый бэкап: плагины, настройки, auth, MCP, memory и skills сохраняются, а checkpoints/сессии/context-mode — нет.

Включить историю старых Pi-сессий:

PI_BACKUP_INCLUDE_SESSIONS=1 \
  ./pi-env-backup.sh backup ~/pi-backups

Включить context-mode индексы:

PI_BACKUP_INCLUDE_CONTEXT=1 \
  ./pi-env-backup.sh backup ~/pi-backups

Включить старые ayu checkpoints (обычно не нужно):

PI_BACKUP_INCLUDE_AYU=1 \
  ./pi-env-backup.sh backup ~/pi-backups

Включить всё сразу:

PI_BACKUP_INCLUDE_SESSIONS=1 \
PI_BACKUP_INCLUDE_CONTEXT=1 \
PI_BACKUP_INCLUDE_AYU=1 \
  ./pi-env-backup.sh backup ~/pi-backups

Настройки, auth, MCP, memory, плагины и skills сохраняются во всех вариантах.

---

4. Восстановить на ноутбуке в WSL

На ноутбуке установи базовые инструменты:

sudo apt update
sudo apt install -y zstd nodejs npm

Передай на ноутбук архив и .sha256 рядом с ним. Проверь архив:

sha256sum -c pi-backup-YYYYMMDD-HHMMSS.tar.zst.sha256

Если бэкап был скачан из этого Git-репозитория, сначала забери LFS-файлы и собери архив из частей:

git lfs pull
chmod +x assemble-pi-backup.sh
./assemble-pi-backup.sh pi-backup-YYYYMMDD-HHMMSS.tar.zst

Скрипт соберёт *.part-* в исходный .tar.zst и сразу проверит контрольную сумму.

Извлеки встроенную копию restore-скрипта:

zstd -dc pi-backup-YYYYMMDD-HHMMSS.tar.zst \
  | tar -xOf - meta/pi-env-backup.sh > pi-env-restore.sh

chmod +x pi-env-restore.sh

Запусти восстановление:

./pi-env-restore.sh restore pi-backup-YYYYMMDD-HHMMSS.tar.zst

Скрипт распакует Pi-среду в домашний каталог текущего пользователя WSL. Если ~/.pi/agent уже существует, он сначала переименует его в каталог вида:

~/.pi/agent.before-restore-YYYYMMDD-HHMMSS

Если Pi ещё не установлен, скрипт установит его так:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

---

5. Проверить восстановление

pi --version
pi list

Запусти Pi в одном из своих проектов:

cd ~/main/имя-проекта
pi

Проверь:

/mcp
/login       # только если OAuth/API-ключ не восстановился

Если какие-то внешние программы нужны плагинам, установи их отдельно: bun, pnpm, uv, gh, jj, docker и т.п. Их бинарники не копируются архивом — архив переносит состояние Pi и список обнаруженных инструментов в meta/MANIFEST.txt.

---

6. Важные замечания

1. Перед созданием архива закрывай Pi, чтобы не копировать активные session/SQLite-файлы.
2. Не используй PI_BACKUP_ALLOW_RUNNING=1, если нет особой причины.
3. Архив — это переносимая копия пользовательской Pi-среды, но не копия всей ОС.
4. Проекты не входят в этот архив: они уже есть в WSL отдельно.
5. Project-local файлы вроде project/.pi/, project/.agents/, AGENTS.md и CLAUDE.md не входят в глобальный архив, если находятся внутри проектов. Их нужно хранить вместе с проектами или отдельно скопировать.
6. Некоторые OAuth-провайдеры могут потребовать повторный /login на новом ноутбуке.