> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gethandshake.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List sessions

> List Handshake sessions and interpret each field and synchronization warning.

List sessions before you search for work or restore a checkpoint.

## List sessions in an agent

Enter:

```text theme={null}
list my sessions
```

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

## List sessions in a terminal

Run:

```bash theme={null}
handshake list
```

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

## Session fields

| Field     | Meaning                                                                       |
| --------- | ----------------------------------------------------------------------------- |
| Session   | The stored session title.                                                     |
| Agent     | The agent that created the session.                                           |
| Updated   | The time since the last stored update.                                        |
| Directory | The working directory. The text output replaces your home directory with `~`. |
| Project   | The project name that Handshake derives.                                      |
| ID        | The native session ID. Use this value when two sessions have similar titles.  |

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:

```json theme={null}
{
  "id": "session-1",
  "title": "Fix authentication flow",
  "agent": "claude-code",
  "updated_at": "2026-07-25T14:30:00Z",
  "updated_relative": "5m ago",
  "working_directory": "/Users/alex/code/payments",
  "project_name": "payments",
  "project_id": "project-1"
}
```

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.