Sessions

A session owns its conversation, model, permission posture, workspace and running work. The background daemon hosts every session, while the chat and the Session Concourse display them.

Session views

Focused chat: The session displayed by the current terminal. Changing focus moves that terminal's focus record to the selected session.
Live row: A session with a runner on the Session Concourse. Its NOW cell shows the reply's last line or the tool the session is running.
Parked row: A chat with no runner, touched within the last week. The board lists at most ten, newest first, and folds older chats into one line. Enter on a parked row paints its transcript and admits the same durable session through the daemon.
NEEDS YOU: A runner that crashed stays on the board with its reason. The user's next act on the session clears the mark, and only a release removes the row.

The board shows the current project's sessions. Each other project with activity paints one door line under OTHER PROJECTS, and the NEEDS YOU rail lists every open question whichever project asked it.

Create a session

To create a session, follow these steps:

Select New Session on the Boot face.
Press Enter.

A blank session opens in the current folder on the model in the chip, with its board row created at the same time.

Creating a session sends no prompt. A further New Session action creates another session while the previous one keeps running. The first session in a folder initializes an empty .mercury/ directory and a project card in Mercury's config home. Browsing the Boot face alone does not initialize the folder.

Continue the latest conversation

To continue the latest conversation, follow these steps:

Run mercury -c or mercury --continue.

Mercury returns to the most recent conversation through the same restoration path used by Continue Last Session.

Resume a named conversation

To resume a named conversation, follow these steps:

Run mercury -r <id|title> with the session's identifier or title.

The transcript opens and the same session becomes available through the daemon.

The session comes back on its own model and effort unless the command line names --model or --effort; then the launch's choice wins and the resume card says so.

The restoration controls are:

/resume: Lists every chat and brings the chosen one back.
Sessions · Projects: Lists sessions above repositories. Tab jumps between the two, highlighting a repository filters the sessions to it, and Enter on a repository opens its most recent chat or, with no history there, a new session.
/sessions: Shows this project's history. a widens the view to all projects.
-w: Runs the session inside a managed worktree.

Name a session

To name a session, follow these steps:

Enter /title <words> in its chat.

The supplied title takes precedence over the automatically generated title.

A session's name has three stages: at birth a ready label, at the first message the first line of the prompt, and after the second reply a short title that the small model writes once, only into an empty name. A name never regresses to an earlier stage. r on a board row renames the session there, and bare /title requests another generated title and incurs a model call.

Park a chat and start fresh

To park a chat and start fresh, follow these steps:

Press Esc if the session is mid-turn.
Enter /clear.

The old session parks with its transcript kept, and a blank session opens in the same folder on the same model.

Close a session from the board

To close a session from the board, follow these steps:

Select its live row on the Session Concourse.
Press Ctrl+X twice.

The first press shows the hint on the row and the second completes. The session stops and its row remains with the next action displayed.

The close chord has these further effects:

Stopped row: Repeating the chord archives the session into PARKED.
Parked row: The chord stages deletion, and the next chord deletes the board record.
Transcript: Deleting the board record leaves the transcript on disk and available through the Boot face and /resume.

Restore a checkpoint

To restore a checkpoint, follow these steps:

Enter /rewind, or its alias /checkpoint.
Select a recorded turn.
Choose the files, the conversation or both.

The session's own runner restores the checkpoint and answers with a receipt. A turn still running is interrupted first.

The File checkpointing setting is the switch for the per-turn file capture. A file edited by hand since the session last touched it refuses the file restore by name, and nothing is written until it is reconciled. A point without saved files offers conversation restoration only, and a point before the last /compact is refused. Conversation restoration retains the session identity and the transcript's recorded rows.

Using Mercury, Agents and teams, Saturn scheduling, Edits and change transactions