Sessions

Sessions are written to ~/.crystal/sessions/<id>.json after each completed turn, and again on an orderly exit when the transcript has a user message. The file stores the transcript, todos, last-request and cumulative token usage, and turn counts.

/quit, or two Ctrl+C presses on an empty composer, leaves the alternate screen and prints the session id and crystal --resume <id>.

Command	Effect
crystal --resume	Choose a session for this workspace at process start
crystal --resume <id>	Load that file and stay in this workspace
crystal --resume <path>	Choose a session from that directory, then enter it
crystal --resume all	Choose a session from any workspace, then enter its directory
/resume	Choose a session for this workspace and replay the transcript
/resume <path>	Choose a session from that directory, then enter it
/resume all	Choose a session from any workspace, then enter its directory
/resume <id>	Load that file and stay in this workspace
/fork	Save the current session and continue from a new id
/fork <id>	Branch that saved session into a new id in the current workspace
/sessions	List resumable sessions for this workspace, newest first
/sessions all	List resumable sessions from every workspace, newest first
/clear	Start a new id

--resume without a value opens the selector before the alternate screen. --workspace and --resume <path> must name the same directory when both are set. A missing or empty session exits without entering the TTY. A redirected terminal cannot open the selector. Pass --resume <id>.

Inside a running session, trust is confirmed before a named directory’s selector opens. Escape leaves the current workspace unchanged. Choosing a session from /resume all asks for trust before entering that directory. Declining trust does not restore the session.

Resume restores the last usage snapshot and cumulative usage, so the status bar, /status, and compaction have a baseline before the next model call. Older files without cumulative usage show an unknown cumulative value, not a partial total. A compacted session restores the full conversation on screen. The model continues from the summary and recent tail. Only the live system prompt is refreshed.

Fork keeps the conversation, model context, todos, Plan/Work mode, turn counters, and usage baseline. It does not copy directory access. The new branch gets the current workspace’s defaults from ~/.crystal/access.json. The source session is unchanged. The branch gets a new creation time, uses the current workspace, and refreshes its live system prompt. Session lists mark the current id and keep the full id for /resume or /fork.