Session List

The session/list method allows Clients to discover sessions known to an Agent. Clients can use this to display session history and switch between sessions. Agents can also push session metadata updates to Clients in real-time via the session_info_update notification, keeping session titles and metadata in sync without polling. Before listing sessions, Clients MUST first complete the initialization phase. Agents that support the session method surface MUST support session/list.

Agents that also advertise session.additionalDirectories may include additionalDirectories in returned SessionInfo objects to report additional workspace roots for listed sessions.

If the Agent advertises the session.delete capability, Clients can remove sessions from future session/list results with session/delete.

Listing Sessions

Clients discover existing sessions by calling the session/list method with optional filtering and pagination parameters:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/list",
  "params": {
    "cwd": "/home/user/project",
    "cursor": "eyJwYWdlIjogMn0="
  }
}

All parameters are optional. A request with an empty params object returns the first page of sessions.

cwd

string

Filter sessions by working directory. Must be an absolute path. Only sessions with a matching cwd are returned.

cursor

string

Opaque cursor token from a previous response’s nextCursor field for cursor-based pagination. See Pagination.

The Agent MUST respond with a list of sessions and optional pagination metadata:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "sessions": [
      {
        "sessionId": "sess_abc123def456",
        "cwd": "/home/user/project",
        "title": "Implement session list API",
        "updatedAt": "2025-10-29T14:22:15Z",
        "_meta": {
          "messageCount": 12,
          "hasErrors": false
        }
      },
      {
        "sessionId": "sess_xyz789ghi012",
        "cwd": "/home/user/another-project",
        "title": "Debug authentication flow",
        "updatedAt": "2025-10-28T16:45:30Z"
      },
      {
        "sessionId": "sess_uvw345rst678",
        "cwd": "/home/user/project",
        "updatedAt": "2025-10-27T15:30:00Z"
      }
    ],
    "nextCursor": "eyJwYWdlIjogM30="
  }
}

sessions

SessionInfo[]

required

Array of session information objects.

Show SessionInfo

sessionId

string

required

Unique identifier for the session.

cwd

string

required

Working directory for the session. Always an absolute path.

additionalDirectories

string[]

If the Agent advertises session.additionalDirectories, it MAY include this field to report the complete ordered additional-root list associated with the listed session. Omitted and empty values are equivalent: this SessionInfo response reports no additional roots. Clients MUST NOT merge this field with prior values or infer additional roots from agent-specific state.

title

string

Human-readable title for the session. May be auto-generated from the first prompt.

updatedAt

string

RFC 3339 timestamp of the last activity in the session.

_meta

object

Agent-specific metadata. See Extensibility.

nextCursor

string

Opaque cursor token. If present, pass this in the next request’s cursor parameter to fetch the next page. If absent, there are no more results.

When no sessions match the criteria, the Agent MUST return an empty sessions array.

Pagination

session/list uses cursor-based pagination. The request includes an optional cursor, and the response includes nextCursor when more results are available.

Clients MUST treat a missing nextCursor as the end of results
Clients MUST treat cursors as opaque tokens — do not parse, modify, or persist them
Agents SHOULD return an error if the cursor is invalid
Agents SHOULD enforce reasonable page sizes internally

Updating Session Metadata

Agents can update session metadata in real-time by sending a session_info_update notification via session/update. This follows the same pattern as other session notifications like available_commands_update and config_option_update.

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "session_info_update",
      "title": "Implement user authentication",
      "_meta": {
        "tags": ["feature", "auth"],
        "priority": "high"
      }
    }
  }
}

All fields are optional. Only include fields that have changed; omitted fields are left unchanged. Set a nullable field to null to clear it.

title

string | null

Human-readable title for the session. Set to null to clear.

updatedAt

string | null

RFC 3339 timestamp of last activity. Set to null to clear.

_meta

object | null

Agent-specific metadata update. Omit to leave unchanged; set to null to clear. See Extensibility.

The sessionId, cwd, and additionalDirectories fields are not included in the update. sessionId is already in the notification’s params, cwd is immutable after session setup, and ACP does not currently define mid-session mutation for additionalDirectories. Agents typically send this notification after the first meaningful exchange to auto-generate a title.

Interaction with Other Session Methods

session/list is a discovery mechanism only — it does not restore or modify sessions:

Client calls session/list to discover available sessions
User selects a session from the list
Client calls session/resume with the chosen sessionId to resume the conversation, optionally setting replayFrom to request history replay

Get Started

Protocol

Libraries

Listing Sessions

Updating Session Metadata

Interaction with Other Session Methods

​Listing Sessions

​Pagination

​Updating Session Metadata

​Interaction with Other Session Methods

Listing Sessions

Pagination

Updating Session Metadata

Interaction with Other Session Methods