24. Sessions & checkpoints#
A session is one conversation plus the work it did, saved continuously. This page covers where sessions live, how to resume and fork them, and how to get back to an earlier point.
Where sessions live#
Every session is one JSON file under ~/.rayu/sessions/:
~/.rayu/sessions/session_fox_1795191775193_b3fe756d07741edb.jsonEach file carries the transcript, the working directory, the provider and model,
the short name, and status metadata. RAYU_HOME or RAYU_CONFIG_DIR relocates
the whole tree.
Because the working directory is recorded with the session, sessions are
effectively per project: rayu --resume opens with the sessions for where you
are, and the picker can search across all of them.
Resume#
| How | What it does |
|---|---|
rayu --resume | Open the session picker |
rayu --resume <id> | Resume one session by id |
/resume (aliases /sessions, /session) | The same picker, from inside a session |
/active | Live sessions: which are working, which are ready |
/catchup | Jump into sessions that finished while you were away |
/back | Return to the session you came from |
/save [label] | Bookmark the session so it sorts to the top |
/unsave | Remove the bookmark |
/rename <name> | Give the session a memorable name |
rayu session rename <id> <name> | The same, from the shell |
The picker searches session names and transcript text, so "the one where we fixed the auth bug" is a usable query.
Fork and transfer#
| Command | What it does |
|---|---|
/fork [prompt] (alias /split) | Open the current conversation in a new window, leaving this one untouched |
/transfer | Open a fresh session with only the compacted context and a copy of the open todos |
rayu cloud fork | Fork into a child session and move the child to a cloud host |
/fork is how you explore two approaches from the same starting point. /transfer
is how you shed history debt without losing the plan.
Rewind#
/rewind is the checkpoint mechanism.
/rewind # show numbered history
/rewind 4 # rewind to message 4, dropping everything after it
/rewind undo # restore the messages the last rewind removedRewinding drops messages from the conversation and resets the provider's session
state, so the model no longer sees what came after. undo puts it back.
Esc on an empty prompt opens the same message selector.
Compaction#
Long conversations eventually crowd the model's context window. Compaction summarizes older messages into a smaller record so work can continue.
/compact # compact now
/compact mode # show the current compaction mode
/compact mode proactive # switch mode for this sessionModes are reactive (compact at a fixed threshold), proactive (compact when the
projected growth says you will hit the threshold soon) and semantic (compact at
topic shifts). Configure defaults in config.toml:
[compaction]
mode = "reactive" # reactive | proactive | semantic
reactive_threshold = 0.80 # context fraction that starts compaction
reactive_threshold_tokens = 400000 # 0 disables the token alternative
lookahead_turns = 15 # proactive projection window/clear starts a brand-new conversation. /cls only clears the rendered view and
keeps the context.
Context inspection#
/contextprints the assembled system prompt sections, the effective tool list, the active messages, and how much of the window is used. This is the honest answer to "why is the model behaving like that", and it costs nothing: it does not run inference or consume a pending memory.
/info shows the shorter version: session id, model, provider, account, and token
counters.
Server and client#
v3 separates the client (your terminal UI) from the server (the daemon that owns agent state). That is what lets several windows share sessions, and what lets an update replace the binary without killing your work.
rayu server start
rayu server reload # hand live sessions to a newer binary
rayu server reload --force
rayu server stop --force # only for a wedged daemonreload preserves headless runs and swarm workers. stop drops them, which is
why it demands --force.
Idle clients release memory instead of staying resident. Configure it in
config.toml:
[session]
hibernation_idle_secs = 1800 # 0 disables
hibernation_mode = "caches" # caches | transcript | exitcaches is instant and lossless; transcript also frees the in-memory
conversation and reloads it on wake; exit leaves a tiny waiter that resumes on
the next key press.
Replay#
rayu replay <session> # replay in the TUI
rayu replay <session> --swarm # replay swarm sessions in sync
rayu replay <session> --export # export the timeline as JSON
rayu replay <session> --auto-edit # compress tool waits and prompt gaps
rayu replay <session> --video out.mp4Cloud sessions#
rayu cloud moves a live session to a remote host and brings it back.
rayu cloud move --session <id> --host <ssh-alias> --attach
rayu cloud return --session <id>
rayu cloud where
rayu cloud status --session <id>
rayu cloud doctorLocal files stay editable while the cloud side works; git reconciles on return with a normal 3-way merge. See the command table in CLI reference → rayu cloud.