List Sessions
listSessionsRead-onlyIdempotent
Retrieve metadata of active Claude CLI sessions, including IDs, models, timing, turn counts, and cumulative cost. Use to identify available sessions before resuming with a session ID.
Instructions
List active Claude CLI sessions tracked by this server. Returns session metadata (IDs, models, timing, turn counts, cumulative cost) for orchestration. Use to check available sessions before resuming with sessionId. No cost (local lookup only).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/index.ts:296-312 (handler)The handler (tool logic) for 'listSessions'. Registered via server.registerTool, calls sessionStore.list() to return all active sessions as JSON.
server.registerTool( "listSessions", { title: "List Sessions", description: listSessionsDescription, inputSchema: {}, annotations: listSessionsAnnotations, }, async () => { const start = Date.now(); const sessions = sessionStore.list(); return { content: [{ type: "text" as const, text: JSON.stringify(sessions, null, 2) }], _meta: buildMeta({ durationMs: Date.now() - start }), }; }, ); - src/annotations.ts:37-42 (schema)Annotations/schema metadata for listSessions: readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=false.
export const listSessionsAnnotations: ToolAnnotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, }; - src/utils/session.ts:79-84 (helper)SessionStore.list() helper: returns all active sessions sorted by lastUsedAt descending. Called by the handler.
list(): SessionEntry[] { this.evictExpired(); return Array.from(this.store.values()) .map((e) => ({ ...e })) .sort((a, b) => b.lastUsedAt - a.lastUsedAt); } - src/utils/session.ts:128-129 (helper)Global SessionStore singleton used by listSessions.
/** Global session store singleton. */ export const sessionStore = new SessionStore(); - src/index.ts:296-312 (registration)Registration of 'listSessions' tool with name, title, description, empty inputSchema, and annotations.
server.registerTool( "listSessions", { title: "List Sessions", description: listSessionsDescription, inputSchema: {}, annotations: listSessionsAnnotations, }, async () => { const start = Date.now(); const sessions = sessionStore.list(); return { content: [{ type: "text" as const, text: JSON.stringify(sessions, null, 2) }], _meta: buildMeta({ durationMs: Date.now() - start }), }; }, );