Сессии и чекпоинты

Каждая беседа с Command Code — это сессия: долговечный транскрипт на диске, который можно возобновить, переименовать, форкнуть, клонировать, откатить, опубликовать и экспортировать. Закройте терминал посреди задачи, вернитесь завтра и продолжите ровно с того места, где остановились.

Что такое сессия?

Сессия — это один JSONL-файл, в который можно только добавлять записи, по одному JSON-объекту на строку. Первая строка — заголовок (идентификатор сессии, время создания, рабочий каталог); каждая следующая строка — запись: ваши сообщения, ответы модели (с расходом токенов и стоимостью), смены модели и уровня усилий, сводки компактации и многое другое.

Записи образуют дерево, а не плоский список. Каждая запись указывает на своего родителя, поэтому сессия может содержать несколько ветвей одной беседы. Именно это обеспечивает работу /rewind, /tree и форков. Сам файл никогда не перезаписывается на месте: навигация по истории лишь перемещает указатель, а новые записи добавляются в конец.

Где лежат файлы сессий

Сессии хранятся для каждого проекта отдельно, ключом служит slug рабочего каталога:

~/.commandcode/projects/<project-slug>/<session-id>.jsonl

Поскольку каталог сессий привязан к проекту, /resume и --continue видят только сессии из того каталога, в котором вы запустили Command Code.

Помимо транскрипта у сессии могут быть сопутствующие файлы:

Файл	Содержимое
<id>.jsonl	Сам транскрипт (заголовок + записи)
<id>.meta.json	Заголовок, модель, происхождение, trace id, статистика компактации
<id>.share.json	Состояние ссылки на публикацию, если сессия публиковалась
<id>.checkpoints.jsonl	Снимки чекпоинтов для /rewind
<id>.prompts.jsonl	История промптов

Как найти файл текущей сессии

# In Command Code session
/session-file

/session-file печатает идентификатор текущей сессии и абсолютный путь к её транскрипту. В терминалах, поддерживающих гиперссылки, путь кликабельный. Если вы ещё не отправили ни одного сообщения, вы увидите пометку (not created yet): транскрипт создаётся при первом сохранении.

Надёжность и устойчивость к сбоям

Сессии устроены так, чтобы вы никогда не теряли зафиксированную работу:

• Фиксация на каждом ходу: каждый завершённый ход добавляется в транскрипт в момент фиксации, а не при выходе. Убейте процесс посреди работы — и всё до последнего зафиксированного хода останется на диске.
• Ход либо фиксируется, либо теряется: разорванного состояния нет: прерванный ход просто не попадает в файл, а сессия чисто возобновляется с предыдущей фиксации.
• Ваши сообщения переживают неудачные ходы: если ход падает на ошибке модели или API, ваше сообщение, открывшее его, всё равно записано на диск, поэтому сессия, которая упала на самом первом ходу, всё равно появится в /resume.
• Пустые сессии не оставляют файла: новая сессия держится в памяти до первого ответа ассистента, поэтому запуск Command Code и выход без реального обмена не засоряют каталог сессий.
• Повреждённые файлы не блокируют запуск: если транскрипт испорчен, битые строки пропускаются, и сессия всё равно загружается.

Начать с чистого листа

В сессии: /clear

# In Command Code session
/clear

/clear начинает новую сессию с пустым контекстом. Предыдущая сессия остаётся на диске и полностью возобновляема через /resume. /new — алиас: та же команда, та же строка меню.

При запуске

Флаг	Что делает
-n, --name <name>	Задаёт отображаемое имя новой сессии при старте
--no-session	Не сохранять сессию на диск вообще (только в памяти)

cmd -n "auth refactor"        # named session
cmd --no-session              # throwaway session, nothing written to disk

Примечание

Сессии --no-session никогда не появляются в /resume и не оставляют транскрипта. Используйте их для экспериментов, которые явно не хотите видеть в истории.

Возобновление

Выбор сессии

# In Command Code session
/resume

/resume (алиас /sessions) открывает выбор сессии — тот же, что даёт cmd -r без аргумента. Он поддерживает поиск, переименование (не выходя из выбора), удаление сессий и фильтрацию по git-ветке, на которой сессия была начата. Форкнутые сессии показывают своё происхождение (fork of <parent>), а текущая сессия подсвечена, и её нельзя удалить.

Два вида сессий скрыты из выбора:

• Headless-сессии (cmd -p) не имеют заголовка и не попадают ни в выбор, ни в --continue, но по точному идентификатору сессии их всё равно можно возобновить.
• Сессии в памяти (--no-session) никогда не записывались на диск.

При запуске

Флаг	Что делает
-r, --resume [name]	Возобновить сессию по id или имени; без аргумента — открыть выбор
--sessions [name]	Алиас --resume
-c, --continue	Продолжить последнюю сессию в текущем каталоге
--session <path|id>	Возобновить по пути к транскрипту (.jsonl) или по уникальному префиксу id сессии
--fork-session	С --resume/--continue/--session: форкнуть найденную сессию в новую, оставив оригинал нетронутым

cmd -r                        # open the resume picker
cmd -r "auth refactor"        # resume by name (or id) — id is tried first, then a case-insensitive title match
cmd -c                        # continue the most recent session here
cmd --session 3f9a            # unique id prefix
cmd --session ~/exported/session.jsonl   # a transcript file directly
cmd -c --fork-session         # branch off the latest session without touching it

Путь, переданный в --session, внутри текущего проекта возобновляется как через -r; путь вне его продолжает дописываться в тот файл, где он лежит.

Модель восстанавливается при возобновлении

Модель, с которой работала сессия, хранится в её метаданных и принимается при возобновлении. /resume внутри сессии всегда принимает модель возобновляемой сессии (сбрасывая переопределение --model при запуске, чтобы победила возобновлённая модель); холодный cmd -r принимает её, если вы явно не передали --model для этого запуска.

Ветвление

Три команды позволяют одной беседе стать многими. Они различаются тем, что переходит вместе с вами:

  original session
    A ── B ── C ── D   ← you are here
         └─ B' ── C'   ← an older branch

  /fork      whole tree + checkpoints
             ┌─────────────────────┐
             │ A ─ B ─ C ─ D       │
             │     └ B' ─ C'       │  /rewind works
             └─────────────────────┘

  /clone     active branch only
             ┌─────────────────────┐
             │ A ─ B ─ C ─ D       │  /rewind empty
             └─────────────────────┘

  /tree      no copy — jump anywhere
             in the tree you already have

/fork [name]: копирует всё

# In Command Code session
/fork
/fork payments-experiment

/fork копирует всю сессию в новую и переключается на неё. Это значит полное дерево со всеми ветвями, а также чекпоинты и историю резервных копий файлов, поэтому /rewind в форке продолжает работать. Оригинал остаётся нетронутым и возобновляемым.

Происхождение записывается в метаданные форка: parentSessionId (исходная сессия) и branchPoint (стабильный id последнего сообщения исходной сессии в точке форка), чтобы выбор сессии мог показывать происхождение fork of <parent>. Имена необязательны (до 200 символов) и должны быть уникальными.

/clone: копирует только текущую ветку

# In Command Code session
/clone

/clone дублирует только активную ветку беседы (от текущей точки назад к корню) в совершенно новый файл сессии и переключается в него. В отличие от /fork, чекпоинты и история файлов намеренно не копируются. Клон — это «дублировать беседу», и /rewind в клоне законно начинается с пустого места. В заголовке нового файла исходный транскрипт записывается как parentSession.

/tree: просмотр всего дерева

# In Command Code session
/tree

/tree открывает навигатор по дереву сессии: все ветви сессии, включая неактивные. Оттуда можно перейти в любую точку дерева, свернуть сегменты, искать, прикреплять метки к записям и переключать фильтры отображения (default, no-tools, user-only, labeled-only). Когда вы уходите с ветки, Command Code может сгенерировать сводку ветки, чтобы работа, которую вы оставляете, оставалась находимой. Сводку можно подтвердить, настроить или пропустить (и задать поведение по умолчанию в /config).

Имена и сведения о сессии

Команда	Что делает
/rename <name>	Переименовать текущую сессию; /rename без аргумента генерирует заголовок моделью
/name	Алиас /rename; /name без аргумента показывает текущее имя
/session-file	Показать id текущей сессии и путь к транскрипту
/status	Показать полный статус окружения
/trace	Скопировать текущий id трейса OpenTelemetry (для поддержки); работает посреди хода, а сохранённые id трейсов переживают возобновление

Имена должны быть уникальными внутри проекта; переименование в занятое имя отклоняется. Имя также становится заголовком вкладки терминала и тем, что разрешает -r <name>.

Чекпоинты и откат

Каждый отправленный промпт открывает чекпоинт: снимок беседы плюс резервную копию каждого файла, который Command Code затем отредактирует. Если что-то пошло не так, откатитесь к любому более раннему чекпоинту и продолжайте оттуда.

Как открыть интерфейс отката

Нажмите Esc дважды в течение 500 мс или выполните:

/rewind

Каждая строка в списке показывает, когда был сделан чекпоинт, превью сообщения, которое его открыло, и сколько файлов изменил этот чекпоинт (или No code changes).

Режимы восстановления

Режим	Что восстанавливает
Both	Восстанавливает беседу и код вместе (рекомендуется).
Conversation only	Удаляет сообщения после чекпоинта. Файлы не трогаются.
Code only	Восстанавливает файлы в состояние на момент чекпоинта. Беседа не трогается.

Чекпоинты, в которых не было изменений файлов, предлагают только Conversation only.

Примечание

Откат удаляет сообщения после чекпоинта и сам чекпоинт. Вы попадаете до сообщения, которое его открыло. Счётчик токенов контекста обновляется, отражая более короткую беседу.

Примечание

Откаты сохраняются. Если вы откатились и затем вышли, при возобновлении сессии вы увидите именно откаченное состояние. Это не предпросмотр.

Что откат файлов делает с рабочим деревом

Откат в режиме Code only или Both делает больше, чем отменяет правки. Он возвращает дерево в прежнее состояние:

Если файл был…	После отката
Изменён после чекпоинта	Восстановлен в состояние на момент чекпоинта
Создан после чекпоинта	Удалён, поскольку на момент чекпоинта его не существовало
Удалён после чекпоинта	Восстановлен

Резервные копии делаются перед каждым вызовом write_file или edit_file и воспроизводятся от новых к старым, поэтому серия правок одного файла возвращается к его самому старому состоянию. Копии побайтово точны, так что бинарные файлы (изображения, скомпилированные артефакты) переживают цикл «копия — восстановление» без изменений, без какой-либо особой обработки.

Восстановление проверяется до запуска

Command Code проверяет, что каждую копию из набора действительно можно восстановить, до того, как что-либо записать, поэтому откат либо применяется целиком, либо не применяется вообще; наполовину восстановленным он вас не оставит. Если файл восстановить нельзя, вам сообщат, какой именно и почему.

Лимиты и приостановка

Чекпоинты хранятся 30 дней, с ограничением 200 резервных копий на сессию. Копии лежат в ~/.commandcode/file-history/<session-id>/, и идентичное содержимое хранится один раз, сколько бы чекпоинтов на него ни ссылалось.

Примечание

Размер резервной копии файла ограничен 10 МБ на файл. Слишком большой файл никогда не читается и не копируется, а поскольку он не был захвачен, откат оставляет его ровно как есть, а не удаляет. Когда сессия достигает предела в 200 копий или проходит 30 дней, старые чекпоинты выбывают.

WARNING

Если на диске заканчивается место, создание чекпоинтов приостанавливается для всей сессии, а не деградирует молча от файла к файлу, и вы увидите уведомление. Уже сделанные чекпоинты остаются рабочими, а создание чекпоинтов возобновляется само, со вторым уведомлением, когда места снова достаточно.

Скретчпад сессии

Каждая сессия получает скретчпад — временное рабочее пространство для промежуточных файлов, которым не место в вашем проекте: заметок анализа, одноразовых скриптов, сгенерированных данных.

/tmp/commandcode-<uid>/<sanitized-cwd>/<session-id>/scratchpad

• Тихий доступ: чтение и запись внутри скретчпада не требуют запросов разрешений (явные правила deny/ask всё равно имеют приоритет). Путь объявляется в системном промпте и экспортируется в shell-команды как $COMMANDCODE_SCRATCHPAD.
• Общий для субагентов: каждый субагент в сессии видит тот же каталог, поэтому агенты могут передавать друг другу промежуточные результаты по имени файла.
• Переживает компактацию: после компактации истории заново вставляется ограниченный манифест скретчпада, содержащий только метаданные, чтобы модель помнила, какие рабочие файлы ещё лежат на диске, не перечитывая их.
• Следует за форками при запуске: форк при запуске через --fork-session копирует скретчпад исходной сессии в форк, поэтому ответвлённая беседа сохраняет свои рабочие файлы.
• Убирается вместе с ретеншеном: скретчпады старше 30 дней вычищаются, а удаление сессии удаляет её скретчпад. Это временное пространство; храните долговечные результаты в самом проекте.

Всё дерево можно перенести переменной окружения COMMANDCODE_SCRATCHPAD_BASE. Создание работает по принципу fail-open: если скретчпад нельзя безопасно создать, функция молча отключается, и сессия работает как обычно без него.

Отключите его полностью в settings.json:

{
  "disableScratchpad": true
}

Совместный доступ и экспорт

/share: переделывается

Публикация по ссылке переделывается. /share без аргумента печатает «Share is being rebuilt, use /export» и не создаёт ссылку. Используйте /export (см. ниже), чтобы сохранить сессию в файл, или /share gist ниже, чтобы опубликовать её на GitHub.

/share gist: gist на GitHub

# In Command Code session
/share gist            # secret gist, default format (html unless configured)
/share gist md         # markdown
/share gist jsonl      # raw transcript

/share gist [html|jsonl|md] рендерит сессию и публикует её как секретный gist на GitHub через CLI gh, затем копирует URL gist. Формат по умолчанию берётся из настройки «Default share gist format» в /config.

/export: записать в файл

# In Command Code session
/export                          # default format to a generated filename
/export md                       # pick a format: html | jsonl | md
/export ~/notes/session.html     # or a path; the extension picks the format

Без пути файл записывается как command-code-session-<first 8 chars of id>.<format> с использованием «Default export format» из /config (html, если не задано). jsonl экспортирует сырой транскрипт.

/copy: в буфер обмена

# In Command Code session
/copy

/copy копирует последний ответ ассистента в буфер обмена. Работает по возможности: в headless- и SSH-терминалах без доступа к буферу строка в ленте сообщает, что скопировать не удалось.

Компакция и журнал сессии

Когда беседа приближается к лимиту контекста, Command Code сжимает историю (автоматически или по /compact). Для сессий важны две гарантии:

• Журнал на диске никогда не перезаписывается: компактация добавляет в дерево транскрипта запись о компактации (сводку плюс указатель на первую запись, сохранённую дословно). Полная история остаётся в файле; при сборке контекста она просто читается через запись о компактации, а /tree по-прежнему может добраться до всего.
• Экономия сохраняется между возобновлениями: накопленная статистика компактации (число событий, всего сэкономленных токенов, последнее событие) записывается в метаданные сессии при каждой компактации, поэтому цифра «total this session», которую сообщает /compact, переживает --resume.

Полное руководство: Контекст и компактация

Что компактация делает с транскриптом, какие есть уровни и их пороги, /compact и /compact-mode, а также как держать контекст компактным.

Проектные решения

• Один выбор, а не два. /resume и /sessions открывают один общий выбор сессий, а не отдельные интерактивное и печатное представления, так что у «где мои сессии» одна ментальная модель.
• Откат разрушителен намеренно, но обратим. Восстановление мгновенно и необратимо в момент выполнения, но поскольку это всего лишь перемещение между чекпоинтами, вы можете откатиться вперёд снова, если передумали.
• Печатные сессии — настоящие сессии. Они сохраняются и возобновляемы, просто по умолчанию скрыты из выбора. Вывод автоматизации не обязан означать одноразовое состояние.

Устранение неполадок

Чекпоинты не появляются

1. Убедитесь, что в сессии отправлено хотя бы одно сообщение.
2. Проверьте, не приостановлено ли создание чекпоинтов (вы должны были увидеть уведомление о нехватке места на диске).
3. Убедитесь, что в сессии были изменения файлов; чекпоинт без изменений файлов предлагает только восстановление беседы.

Восстановление не удалось

1. Посмотрите в сообщении об ошибке, какой файл не удалось восстановить.
2. Убедитесь, что файлы резервных копий не были удалены вручную из ~/.commandcode/file-history/.
3. Проверьте, что у вас есть права на запись в целевые файлы.

Двойной Esc не работает

1. Нажмите Esc дважды в течение 500 мс.
2. Убедитесь, что фокус находится в поле ввода Command Code.
3. Используйте вместо этого /rewind.

Советы

• Давайте имена сессиям, к которым вернётесь: /rename auth-refactor (или запуск с -n) превратит cmd -r auth-refactor в однострочник, а /rename без аргумента сгенерирует вам приличный заголовок.
• Форкайте перед рискованными экспериментами: cmd -c --fork-session или /fork даёт полную копию, включая чекпоинты, а оригинал остаётся чистым.
• Используйте /clone, чтобы прибраться: после обильных откатов /clone выносит только ту ветку, которую вы сохранили, в чистую новую сессию.
• Помечайте важные точки в /tree: метки переживают форки и делают длинные деревья обозримыми.
• Позвольте скретчпаду впитывать беспорядок: просите одноразовые скрипты и промежуточные результаты класть в скретчпад — без запросов разрешений, без файлов, засоряющих репозиторий, и с автоматической уборкой.
• /share gist перед парным программированием: опубликуйте сессию как секретный gist, чтобы коллега прочитал, что вы уже пробовали.
• Берите /trace, когда что-то ломается: id трейса нужен поддержке, его можно скопировать посреди хода, а прошлые id переживают возобновление.

См. также

• Headless-режим: возобновление сессий и имена из скриптов и CI.
• Интерактивный режим: полный опыт работы с сессией.
• Контекст и компактация: как история суммируется по мере роста.
• Режимы разрешений: как решения о разрешениях применяются при возобновлении или форке сессии.

Источник

Сверено с оригиналом 13 ноября 2026.