list_sessions
Retrieve all Claude Code conversation sessions within a specified project to manage and review ongoing discussions.
Instructions
List all sessions in a project
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_name | Yes | Project folder name (e.g., '-Users-young-works-myproject') |
Implementation Reference
- src/mcp/index.ts:29-34 (handler)MCP tool handler for 'list_sessions': invokes session.listSessions(project_name) and returns the result as formatted JSON text content.
async ({ project_name }) => { const result = await Effect.runPromise(session.listSessions(project_name)) return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], } } - src/mcp/index.ts:26-28 (schema)Zod input schema defining the 'project_name' parameter for the list_sessions tool.
{ project_name: z.string().describe("Project folder name (e.g., '-Users-young-works-myproject')"), }, - src/mcp/index.ts:23-35 (registration)Registration of the 'list_sessions' tool on the McpServer instance.
server.tool( 'list_sessions', 'List all sessions in a project', { project_name: z.string().describe("Project folder name (e.g., '-Users-young-works-myproject')"), }, async ({ project_name }) => { const result = await Effect.runPromise(session.listSessions(project_name)) return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], } } ) - src/lib/session.ts:57-101 (helper)Core implementation of listSessions: reads session files in a project directory, parses messages, extracts metadata (title from first human message, counts, timestamps), returns array of SessionMeta objects.
export const listSessions = (projectName: string) => Effect.gen(function* () { const projectPath = path.join(getSessionsDir(), projectName) const files = yield* Effect.tryPromise(() => fs.readdir(projectPath)) const sessionFiles = files.filter((f) => f.endsWith('.jsonl')) const sessions = yield* Effect.all( sessionFiles.map((file) => Effect.gen(function* () { const filePath = path.join(projectPath, file) const content = yield* Effect.tryPromise(() => fs.readFile(filePath, 'utf-8')) const lines = content.trim().split('\n').filter(Boolean) const messages = lines.map((line) => JSON.parse(line) as Message) const sessionId = file.replace('.jsonl', '') const firstMessage = messages[0] const lastMessage = messages[messages.length - 1] // Extract title from first user message const title = pipe( messages, A.findFirst((m) => m.type === 'human'), O.map((m) => { const msg = m.message as { content?: string } | undefined const content = msg?.content ?? '' return content.slice(0, 50) + (content.length > 50 ? '...' : '') }), O.getOrElse(() => 'Untitled') ) return { id: sessionId, projectName, title, messageCount: messages.length, createdAt: firstMessage?.timestamp, updatedAt: lastMessage?.timestamp, } satisfies SessionMeta }) ), { concurrency: 10 } ) return sessions })