list_sessions
Browse and search Claude Code conversation history by project or date to find relevant sessions using local semantic and keyword indexing.
Instructions
List all indexed Claude Code sessions. Use when the user wants to browse conversation history or find sessions by project/date.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | ||
| limit | No | ||
| sort | No |
Implementation Reference
- src/tools/list-sessions.ts:10-81 (handler)The handler function 'handleListSessions' that retrieves sessions from the database based on project filters and sorting preferences.
export async function handleListSessions( db: Database.Database, params: ListSessionsParams ): Promise<{ content: Array<{ type: string; text: string }> }> { const limit = Math.min(params.limit || 20, 100); const sortDir = params.sort === "oldest" ? "ASC" : "DESC"; let filterClause = ""; const queryParams: unknown[] = []; if (params.project) { filterClause = "WHERE p.name LIKE ?"; queryParams.push(`%${params.project}%`); } const sessions = db .prepare( `SELECT s.session_id, p.path as project, p.name as project_name, s.branch, s.started_at, s.model, s.intent, s.turn_count, s.indexed_at IS NOT NULL as indexed, (SELECT COUNT(*) FROM chunks c WHERE c.session_id = s.id) as chunk_count FROM sessions s JOIN projects p ON p.id = s.project_id ${filterClause} ORDER BY s.started_at ${sortDir} LIMIT ?` ) .all(...queryParams, limit) as any[]; const totalSessions = ( db.prepare("SELECT COUNT(*) as count FROM sessions").get() as any ).count; const totalIndexed = ( db .prepare( "SELECT COUNT(*) as count FROM sessions WHERE indexed_at IS NOT NULL" ) .get() as any ).count; // Project summary with registered status const userConfig = loadUserConfig(); const registeredSet = new Set(userConfig.indexed_projects); const projects = db .prepare( `SELECT p.dir_name, p.name, p.path, COUNT(s.id) as session_count FROM projects p LEFT JOIN sessions s ON s.project_id = p.id GROUP BY p.id ORDER BY session_count DESC` ) .all() as any[]; const result = { sessions: sessions.map((s: any) => ({ ...s, indexed: Boolean(s.indexed), })), total_sessions: totalSessions, total_indexed: totalIndexed, projects: projects.map((p: any) => ({ name: p.name, path: p.path, session_count: p.session_count, registered: registeredSet.has(p.dir_name), })), }; return { content: [{ type: "text", text: JSON.stringify(result) }] }; } - src/tools/list-sessions.ts:4-8 (schema)Type definition for the input parameters of 'list_sessions'.
export interface ListSessionsParams { project?: string; limit?: number; sort?: "recent" | "oldest"; } - src/server.ts:84-99 (registration)Registration of the 'list_sessions' tool in the MCP server setup.
// list_sessions tool server.tool( "list_sessions", "List all indexed Claude Code sessions. Use when the user wants to browse conversation history or find sessions by project/date.", { project: z.string().optional(), limit: z.number().optional(), sort: z.enum(["recent", "oldest"]).optional(), }, async (args): Promise<ToolResult> => { return handleListSessions(db, { project: args.project, limit: args.limit, sort: args.sort, }); }