Claude Historian

Instructions

Implementation Reference

• src/index.ts:340-353 (handler)

  MCP tool handler for 'list_recent_sessions': extracts parameters, calls UniversalHistorySearchEngine.getRecentSessions, formats with BeautifulFormatter.formatRecentSessions, and returns formatted text content.
  case 'list_recent_sessions': { const limit = (args?.limit as number) || 10; const project = args?.project as string; const universalResult = await this.universalEngine.getRecentSessions(limit, project); const formattedResult = this.formatter.formatRecentSessions( universalResult.results as any, project ); return { content: [{ type: 'text', text: formattedResult }], }; }
• src/index.ts:159-180 (schema)

  Input schema and registration for 'list_recent_sessions' tool in ListToolsRequest handler.
  name: 'list_recent_sessions', description: 'Browse recent sessions with smart activity detection and summaries', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Maximum number of sessions (default: 10)', default: 10, }, project: { type: 'string', description: 'Optional project name to filter sessions', }, include_summary: { type: 'boolean', description: 'Include intelligent session summaries (default: true)', default: true, }, }, }, },
• src/search.ts:1295-1377 (handler)

  Core implementation of getRecentSessions in HistorySearchEngine: scans recent .jsonl files across projects in parallel, extracts session metadata (duration, tools, accomplishments, etc.), sorts by recency, limits to requested number.
  async getRecentSessions(limit: number = 10): Promise<any[]> { try { // OPTIMIZED: Fast session discovery with parallel processing and early termination const projectDirs = await findProjectDirectories(); // PERFORMANCE: Limit projects and use parallel processing like GLOBAL const limitedDirs = projectDirs.slice(0, 10); // Limit projects for speed // PARALLEL PROCESSING: Process projects concurrently const projectResults = await Promise.allSettled( limitedDirs.map(async (projectDir) => { const jsonlFiles = await findJsonlFiles(projectDir); const decodedPath = projectDir.replace(/-/g, '/'); const projectName = decodedPath.split('/').pop() || 'unknown'; // PERFORMANCE: Limit files per project and process in parallel const limitedFiles = jsonlFiles.slice(0, 5); // Limit files for speed const sessionResults = await Promise.allSettled( limitedFiles.map(async (file) => { const messages = await this.parser.parseJsonlFile(projectDir, file); if (messages.length === 0) return null; // Fast extraction of session data const toolsUsed = [...new Set(messages.flatMap((m) => m.context?.toolsUsed || []))]; const startTime = messages[0]?.timestamp; const endTime = messages[messages.length - 1]?.timestamp; // Quick duration calculation let realDuration = 0; if (startTime && endTime) { realDuration = Math.round( (new Date(endTime).getTime() - new Date(startTime).getTime()) / 60000 ); } // Extract accomplishments - what was actually done const accomplishments = this.extractSessionAccomplishments(messages); return { session_id: file.replace('.jsonl', ''), project_path: decodedPath, project_dir: projectDir, project_name: projectName, message_count: messages.length, duration_minutes: realDuration, end_time: endTime, start_time: startTime, tools_used: toolsUsed.slice(0, 5), // Limit tools for speed assistant_count: messages.filter((m) => m.type === 'assistant').length, error_count: messages.filter((m) => m.context?.errorPatterns?.length).length, session_quality: this.calculateSessionQuality(messages, toolsUsed, []), accomplishments: accomplishments.slice(0, 3), // Top 3 accomplishments }; }) ); // Collect successful session results return sessionResults .filter((result) => result.status === 'fulfilled' && result.value) .map((result) => (result as PromiseFulfilledResult<any>).value); }) ); // Flatten and collect all sessions const realSessions: any[] = []; for (const result of projectResults) { if (result.status === 'fulfilled') { realSessions.push(...result.value); } } // Sort by real end time return realSessions .filter((s) => s.end_time) // Only sessions with real timestamps .sort((a, b) => new Date(b.end_time).getTime() - new Date(a.end_time).getTime()) .slice(0, limit); } catch (error) { console.error('Recent sessions error:', error); return []; } }
• src/formatter.ts:739-763 (helper)

  Formatter for recent sessions results: ranks by productivity, structures JSON output with session details (id, ts, duration, messages, project, tools, accomplishments), adds robot emoji header.
  formatRecentSessions(sessions: any[], project?: string): string { const filter = project ? `"${project}"` : 'all'; const header = `${robots.sessions} ${filter} | ${sessions.length} sessions`; if (sessions.length === 0) { return `${header}\n\n{"sessions":[]}`; } const rankedSessions = this.rankSessionsByProductivity(sessions); const topSessions = rankedSessions.slice(0, 10); const structured = { sessions: topSessions.map((s) => ({ id: s.session_id?.substring(0, 8) || null, ts: this.formatTimestamp(s.end_time || s.start_time), duration: s.duration_minutes || 0, messages: s.message_count || 0, project: s.project_path?.split('/').pop() || null, tools: s.tools_used || null, accomplishments: s.accomplishments || null, })), }; return `${header}\n\n${JSON.stringify(structured, null, 2)}`; }
• src/universal-engine.ts:1403-1424 (helper)

  UniversalHistorySearchEngine.getRecentSessions: delegates to HistorySearchEngine.getRecentSessions, adds enhanced flag if Claude Desktop available (though no Desktop sessions currently).
  // Universal methods for all tools async getRecentSessions(limit?: number, project?: string): Promise<UniversalSearchResult> { await this.initialize(); const claudeCodeSessions = await this.claudeCodeEngine.getRecentSessions(limit || 10); if (!this.claudeDesktopAvailable) { return { source: 'claude-code', results: claudeCodeSessions as any, enhanced: false, }; } // For sessions, Desktop doesn't have traditional sessions, so we focus on Code // But we mark as enhanced if Desktop is available for future Desktop session support return { source: 'claude-code', results: claudeCodeSessions as any, enhanced: this.claudeDesktopAvailable, }; }