Облако и локальная разработка

Что на самом деле делает forge-cli

forge-cli — небольшой бинарник на Go (около 6 МБ), закрывающий три сценария: авторизацию, просмотр сессий и двустороннюю синхронизацию. В паре с ним работает forge-hook, который ставится хуком Claude Code, чтобы каждый локальный ход автоматически становился облачным снимком.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# Разовая настройка
forge link                     # авторизация device flow, токен в ~/.config/forge/token
forge-hook install             # хуки Claude Code (turn-start, turn-finish)

# Просмотр облачных сессий
forge session list --repo simple-container-com/forge --branch feature/auth
forge session get <session-id>
forge cloud-continue <session-id> -m "fix the test that's failing"

# Ручная синхронизация
forge sync                     # локально → облако (полная отправка состояния)
forge sync --from-cloud        # облако → локально (забрать + git checkout + транскрипт)

# Просмотр и настройка
forge status
forge config
forge config set provider anthropic-us-east-1
forge unlink                   # удалить доступы и хуки

Как работают хуки

Когда вы ведёте сессию Claude Code локально, forge-hook срабатывает дважды за ход:

turn-start — читает промпт со стандартного ввода (или из --prompt-file). Отправляет в облако событие «ход начался». Если сети нет, событие уходит в офлайн-очередь.

turn-finish — основной хук. Собирает снимок из вывода сессии Claude (журнал сообщений, использованная модель, расход токенов). Вызывает POST /v1/sessions/{sessionId}/turns/start, чтобы получить идентификаторы хода и снимка. Загружает журнал сообщений (в S3, если настроен, иначе встроенно). Закрывает ход через POST .../turns/{turnId}/finish. При сбое — в офлайн-очередь.

Офлайн-очередь повторов

Когда сеть капризничает, снимки не теряются — они лежат в ~/.config/forge/queue/{sessionId}.jsonl (один файл на сессию, одна строка на ожидающий снимок). Политика повторов:

Фоновая горутина разбирает очередь при восстановлении связи; forge-hook drain делает это вручную. Успешный разбор уплотняет файл очереди. CLI предупреждает, если в сессии накопилось больше нескольких ожидающих записей — обычно это признак неверно настроенного эндпоинта API, а не того, что вы действительно так долго офлайн.

Запускайте рантайм где угодно

Рантайм Forge — один бинарник, которому всё равно, где он работает. Подойдёт любая машина с сетевым доступом к вашим git-удалёнкам и эндпоинтам провайдеров ИИ: ноутбук, домашний сервер, облачная виртуалка за пять долларов, Kubernetes или GitHub Actions.

Голое железо или любая виртуалка — вариант по умолчанию. Запустите forge-runtime обычным процессом. Работает на Linux, macOS и везде, где запускается бинарник Go. Идеально для домашних серверов, выделенных машин разработки и дешёвых облачных инстансов. Оркестрация контейнеров не нужна.

GitHub Actions — лучше всего подходит под «я работаю над этим репозиторием, прогони агента по этой ветке». Шаблон процесса (claude-session-workflow.yml) выкачивает репозиторий, забирает журнал сообщений, запускает Claude, коммитит результат и отправляет обратный вызов finish с JWT на задание. Отправить можно через forge cloud-continue или кнопкой «Продолжить в облаке» в интерфейсе.

Kubernetes — лучше всего для высокопроизводительных пулов агентов и постоянных сессий. Облачная нагрузка запускает Claude внутри пода, прогоняет вывод через forge-stream-relay и сохраняет снимок через сервис сессий. Пулы воркеров могут объявлять метки provider (для маршрутизации) и affinity (закрепление по аренде).

Все три режима используют один формат сессии, одну схему снимка и один протокол синхронизации. Переключение между ними — изменение конфигурации, а не архитектуры.

Постоянные сессии и аренда

Бэкенд Kubernetes поддерживает аренду сессии, чтобы многоходовые конвейеры выполнялись на одном поде, когда это имеет смысл:

• Режим на ход (по умолчанию): каждый ход берёт свободного воркера. Дёшево, без привязки.
• Режим на сессию: ходы со второго и далее держатся воркера, обработавшего первый, в пределах TTL простоя в 30 минут. По истечении возвращается режим на ход.

Аренда живёт в ветках forge/session/<sid>/turn-<n> в сервисе сессий. Её держит воркер, последним трогавший сессию, и продлевает автоматически, пока он здоров.

Двусторонняя синхронизация, картинкой

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[ Локальный Claude Code ] ── forge-hook turn-finish ──► [ Облачная сессия ]
                                                                  │
                                                                  ▼
                                                    [ Интерфейс: продолжить ]
                                                                  │
                                                                  ▼
                                              [ отправка процесса / под K8s ]
                                                                  │
                                                                  ▼
[ Локальная рабочая копия ] ◄─ forge sync --from-cloud ◄─ [ Обновлённая сессия ]

Передача симметрична. Можно начать в одном месте, переключиться и вернуться. Всё, что сохраняется — журнал сообщений, снимок, ветка, транскрипт, — переживает круг целиком.

Квоты на организацию

Облачный бэкенд учитывает каждый ход: расход токенов, оценку стоимости, провайдера, пул воркеров, длительность. Квоты организации (вычисления, токены, деньги) применяются до отправки хода. Состояние квот видно в интерфейсе, поэтому администраторы наблюдают расход в реальном времени.

Что вы получаете

Всё перечисленное уже работает в продакшене.

• forge link device flow и хранилище доступов
• forge session list / get — просмотр облачных сессий
• forge sync и forge sync --from-cloud
• forge cloud-continue — отправка процесса
• forge-hook install / uninstall / drain
• Офлайн-очередь повторов
• Бэкенд GitHub Actions — шаблон процесса и отправка
• Бэкенд Kubernetes — облачное выполнение и трансляция потока
• Квоты организации — и учёт, и применение

Что лежит в ~/.config/forge/

1
2
3
4
5
6

~/.config/forge/
├── config.toml          # данные организации, провайдер по умолчанию, уровень логов
├── token                # device JWT (права 0600, атомарное переименование при ротации)
└── queue/
    ├── ses_01HXXX.jsonl
    └── ses_01HYYY.jsonl

Ничего экзотического — текст на диске. Легко посмотреть, легко сохранить, легко снести, если хочется начать с чистого листа (forge unlink && rm -rf ~/.config/forge).

Попробовать

CLI forge — один бинарник под платформу, без зависимостей рантайма: тот же способ установки, что у sc . Как только он в вашем PATH:

1
2
3
4

forge link
forge-hook install
# дальше работайте в Claude Code как обычно
# каждый ход сам синхронизируется с https://forge.simple-container.com