Skip to main content
Every interactive run of the CLI is a session: the transcript, the tool calls, and the context Cortex built up along the way. Sessions are written to disk as the work happens, so closing the terminal does not lose anything and you can pick the work back up later. The CLI also remembers which coding session belongs to which workspace, so a terminal turn continues the same work you see in the web app. This page covers the commands that act on sessions from your shell, the in-session commands that act on the one you are in, rewinding and forking, export and import, sharing a link, protecting a session from cleanup, and where the files live.

​
Six commands from the shell

Rewinding, forking and sharing are things you do inside a session, with /rewind, /fork and /share. There is no cortex rewind, cortex fork or cortex share command, and the --share flag on cortex run is declared but refused: it stops the run with --share is not supported by the Code service contract. No turn was submitted.

​
List sessions

By default this shows the sessions started in the current directory.

​
Resume

--no-session is declared on the same command but cannot be combined with it: resuming with it set fails with --no-session is incompatible with resume. Treat it as a flag for the command reference rather than a daily control. The picker lists recent sessions with what each one was about; typing filters the list, and the footer strip at the bottom of the screen names the keys that apply to it, including starting a new session instead. Inside a running session, /resume opens the same picker and Ctrl+r searches past sessions. Non-interactive runs can continue a session too: cortex run --continue picks up the most recent one and cortex run --session <SESSION_ID> continues a named one. A goal comes back with the session it belongs to.

​
Start fresh, or clear the conversation

/new starts a new session without leaving the TUI. /clear empties the conversation but keeps the session you are in; it asks first and tells you what is dropped and what is kept, because your files and your configuration are untouched either way. /session prints the details of the session you are in, /rename gives it a name, and /timeline shows its timeline. /favorite and /unfavorite mark and unmark it, and f toggles the mark on the selected row in the sessions panel.

​
Rewind, undo, fork

Press Esc twice in quick succession to open the rewind overlay, which walks back through the session to an earlier point. The overlay has its own keys and lists them while it is open. From the composer:
  • /rewind optionally takes a number of steps.
  • /undo and /redo step the last action back and forward.
  • /fork starts a new session from this one, optionally with a name, leaving the original as it was.
  • /ghost manages ghost commits for undo.
Forking is the safe way to try a second approach: the fork carries the conversation so far, and anything you do in it stays out of the original.

​
Export

From inside a session, /export offers Markdown, JSON or plain text and writes a file named in the pattern cortex_<title>_<date>.<ext>.

​
Import

Import is how a session moves between machines, and with - it composes with anything that can write JSON to a pipe. /share creates a link to the session. It takes a duration, and the values it accepts are 30d, 24h, 60m and never. Sharing is an in-session action only: cortex run --share is refused before the run starts.

​
Protect a session from cleanup

cortex lock is also available as cortex protect. A locked session survives the cleanup commands below, which makes it the right thing to do to the session you will want to point at in three months. The reason you give with -r is there so the lock explains itself later.

​
Delete and clean up

-y/--yes skips the confirmation, and -f/--force is accepted as well. Housekeeping across everything the CLI has written is a separate command, cortex compact, also available as cortex gc and cortex cleanup:
It also takes logs, vacuum and config subcommands.

​
Where sessions live

Sessions are files under the Cortex home directory, one directory per session at ~/.cortex/sessions/{session-id}/. A session with a goal keeps it alongside as its own file, which is why a goal survives resuming and compaction. ~/.cortex/code-sessions.json is the map from a workspace to the coding session it belongs to. Two configuration keys govern the history file:
Setting persistence to none is the way to run without a stored history at all. See Data locations for everything the CLI writes and Configuration for where to set these.