Skip to main content
List sessions before you search for work or restore a checkpoint.

​
List sessions in an agent

Enter:
The agent calls list_sessions and presents the sessions in update order.

​
List sessions in a terminal

Run:
On an interactive terminal, this command opens the terminal interface. When you pipe the output, the command writes plain text.

​
Session fields

Handshake derives the project name in this order:
  1. Repository name from the Git remote.
  2. Repository root directory name.
  3. Session working directory name.
  4. No value when the source data has no project information.

​
Structured MCP result

The list_sessions tool returns these fields for each session:
The structured result keeps the absolute working directory. It also includes a warnings array.

​
Synchronization warnings

A synchronization warning means that Handshake could not import one or more native sessions during the list operation. Handshake still returns the sessions that it can read. Examples include:
  • The agent storage is not available.
  • One or more Codex sessions could not be imported.
Read warnings below the session list. Correct the storage or permission problem, and list the sessions again.