Skip to main content
The session/list method returns the sessions an Agent knows about. Clients use it to show session history and let users switch between sessions. Agents can also send a session_info_update notification when a session’s title or metadata changes, so Clients don’t have to poll. Before listing sessions, Clients MUST first complete the initialization phase to verify the Agent supports this capability.

Checking support

Before attempting to list sessions, Clients MUST verify that the Agent supports this capability by checking the sessionCapabilities.list field in the initialize response:
If sessionCapabilities.list is not present, the Agent does not support listing sessions and Clients MUST NOT attempt to call session/list. Agents that also advertise sessionCapabilities.additionalDirectories may include additionalDirectories in returned SessionInfo objects to report additional workspace roots for listed sessions.
If the Agent advertises the sessionCapabilities.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:
All parameters are optional. A request with an empty params object returns the first page of sessions.
string
Filter sessions by working directory. Must be an absolute path. Only sessions with a matching cwd are returned.
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:
SessionInfo[]
required
Array of session information objects.
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, which means not parsing, modifying, or persisting them
  • Agents SHOULD return -32602 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 current_mode_update.
All fields are optional. Only include fields that have changed. Omitted fields are left unchanged.
string | null
Human-readable title for the session. Set to null to clear.
string | null
ISO 8601 timestamp of last activity. Set to null to clear.
object
Agent-specific metadata. 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 only discovers sessions. It does not restore or modify them:
  1. Client calls session/list to discover available sessions
  2. User selects a session from the list
  3. Client calls session/load with the chosen sessionId to resume the conversation

Archived sessions (unstable)

Agents that advertise sessionCapabilities.archive support session/archive, session/unarchive, the archived filter on session/list, and archived on each listed session. Agents that advertise it MUST also advertise sessionCapabilities.list. Clients MUST NOT use any of them unless the Agent advertises the capability. See the RFD. Archiving hides a session from default session/list results. Unarchiving returns it. Both keep the session ID and saved history, and both take only a sessionId and return an empty result:
The archived filter on session/list selects sessions by archive state: Agents MUST reject a value they don’t support with -32602 rather than falling back to exclude. The filter combines with cwd and applies before pagination. Clients keep the same cwd and archived values when following nextCursor. Agents that advertise the capability MUST include a boolean archived on every listed session.
  • If the session is loaded, session/archive cancels any ongoing work and frees the session’s resources as if session/close had been called, then archives it. This does not require the close capability.
  • session/unarchive never loads or resumes a session. Clients that want to continue an archived session SHOULD unarchive it before calling session/load or session/resume. Agents MAY reject session/load or session/resume for an archived session.
  • Archive state persists across connections and restarts. Closing, loading, or resuming a session does not change it.
  • Because archiving closes the session, session/status reports an archived session as saved.
  • Archiving an archived session, or unarchiving one that isn’t archived, succeeds. A session that does not exist gets -32002.
  • Deleted sessions are excluded from every filter value, and unarchiving does not restore them.