Claude Historian

Instructions

Implementation Reference

• src/search.ts:666-781 (handler)

  Core handler function implementing the find_file_context tool logic. Searches conversation JSONL files across multiple projects in parallel for references to the specified filePath using enhanced matching patterns (context.filesReferenced, content mentions, git diffs). Filters low-value content, deduplicates, infers operation types, limits messages per context, and returns FileContext[] sorted by recency.
  async findFileContext(filePath: string, limit: number = 25): Promise<FileContext[]> { const fileContexts: FileContext[] = []; try { const projectDirs = await findProjectDirectories(); // COMPREHENSIVE: Process more projects to match GLOBAL's reach const limitedDirs = projectDirs.slice(0, 15); // Increased significantly to match GLOBAL scope // PARALLEL PROCESSING: Process all projects concurrently const projectResults = await Promise.allSettled( limitedDirs.map(async (projectDir) => { const jsonlFiles = await findJsonlFiles(projectDir); // COMPREHENSIVE: Process more files to match GLOBAL's reach const limitedFiles = jsonlFiles.slice(0, 10); // Increased to match GLOBAL scope const fileResults = await Promise.allSettled( limitedFiles.map(async (file) => { const messages = await this.parser.parseJsonlFile(projectDir, file); const fileMessages = messages.filter((msg) => { // ENHANCED file matching logic like GLOBAL with more patterns const hasFileRef = msg.context?.filesReferenced?.some( (ref) => { const refLower = ref.toLowerCase(); const pathLower = filePath.toLowerCase(); // More comprehensive matching patterns return refLower.includes(pathLower) || pathLower.includes(refLower) || refLower.endsWith('/' + pathLower) || pathLower.endsWith('/' + refLower) || refLower.split('/').pop() === pathLower || pathLower.split('/').pop() === refLower || refLower === pathLower || refLower.includes(pathLower.replace(/\\/g, '/')) || refLower.includes(pathLower.replace(/\//g, '\\')); } ); // Enhanced content matching with case variations and path separators const contentLower = msg.content.toLowerCase(); const pathVariations = [ filePath.toLowerCase(), filePath.toLowerCase().replace(/\\/g, '/'), filePath.toLowerCase().replace(/\//g, '\\'), filePath.toLowerCase().split('/').pop() || '', filePath.toLowerCase().split('\\').pop() || '' ]; const hasContentRef = pathVariations.some(variation => variation.length > 0 && contentLower.includes(variation) ); // Enhanced git pattern matching const hasGitRef = /(?:modified|added|deleted|new file|renamed|M\s+|A\s+|D\s+)[\s:]*[^\n]*/.test(msg.content) && pathVariations.some(variation => variation.length > 0 && contentLower.includes(variation) ); return hasFileRef || hasContentRef || hasGitRef; }); if (fileMessages.length > 0) { // Claude-optimized filtering - preserve valuable context const cleanFileMessages = fileMessages.filter(msg => { return msg.content.length > 15 && !this.isLowValueContent(msg.content); }); const dedupedMessages = SearchHelpers.deduplicateByContent(cleanFileMessages); if (dedupedMessages.length > 0) { // Group by operation type (heuristic) const operationType = SearchHelpers.inferOperationType(dedupedMessages); return { filePath, lastModified: dedupedMessages[0]?.timestamp || '', relatedMessages: dedupedMessages.slice(0, Math.min(limit, 10)), // More context for Claude operationType, }; } } return null; }) ); // Collect successful file results const validContexts: FileContext[] = []; for (const result of fileResults) { if (result.status === 'fulfilled' && result.value) { validContexts.push(result.value); } } return validContexts; }) ); // Aggregate all results from parallel processing for (const result of projectResults) { if (result.status === 'fulfilled') { fileContexts.push(...result.value); } } return fileContexts.sort( (a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime() ); } catch (error) { console.error('File context search error:', error); return []; } }
• src/universal-engine.ts:1064-1095 (helper)

  Helper wrapper in UniversalHistorySearchEngine that extends the core findFileContext to also search Claude Desktop storage (LocalStorage, IndexedDB via micro-copy and text search) if available, combining results from both sources.
  async findFileContext( filepath: string, limit?: number ): Promise<{ source: string; results: FileContext[]; enhanced: boolean }> { await this.initialize(); const claudeCodeResults = await this.claudeCodeEngine.findFileContext(filepath, limit); if (!this.claudeDesktopAvailable) { return { source: 'claude-code', results: claudeCodeResults, enhanced: false }; } const desktopMessages = await this.searchClaudeDesktopConversations( filepath, undefined, limit ); const combinedResults = this.combineFileContextResults(claudeCodeResults, desktopMessages); const hasDesktopData = desktopMessages.length > 0; return { source: hasDesktopData ? 'claude-desktop' : 'claude-code', results: combinedResults, enhanced: hasDesktopData }; }
• src/index.ts:77-106 (registration)

  MCP tool registration in main server (src/index.ts), defining name, description, and input schema for find_file_context.
  { name: 'find_file_context', description: 'Find all conversations and changes related to a specific file', inputSchema: { type: 'object', properties: { filepath: { type: 'string', description: 'File path to search for in conversation history', }, operation_type: { type: 'string', description: 'Filter by operation: read, edit, create, or all', enum: ['read', 'edit', 'create', 'all'], default: 'all', }, limit: { type: 'number', description: 'Maximum number of results (default: 15)', default: 15, }, detail_level: { type: 'string', description: 'Response detail: summary (default), detailed, raw', enum: ['summary', 'detailed', 'raw'], default: 'summary', }, }, required: ['filepath'], },
• dxt/server.js:78-107 (registration)

  MCP tool registration in DXT server (dxt/server.js), defining name, description, and input schema for find_file_context.
  { name: 'find_file_context', description: 'Find all conversations and changes related to a specific file', inputSchema: { type: 'object', properties: { filepath: { type: 'string', description: 'File path to search for in conversation history' }, operation_type: { type: 'string', description: 'Filter by operation: read, edit, create, or all', enum: ['read', 'edit', 'create', 'all'], default: 'all' }, limit: { type: 'number', description: 'Maximum number of results (default: 15)', default: 15 }, detail_level: { type: 'string', description: 'Response detail: summary (default), detailed, raw', enum: ['summary', 'detailed', 'raw'], default: 'summary' } }, required: ['filepath'] }
• src/index.ts:272-302 (handler)

  Server-side MCP CallToolRequest handler dispatch for find_file_context: extracts params, calls universalEngine.findFileContext, formats output with BeautifulFormatter adding source/action headers, returns MCP content response.
  case 'find_file_context': { const universalResult = await this.universalEngine.findFileContext( args?.filepath as string, (args?.limit as number) || 15 ); const detailLevel = (args?.detail_level as string) || 'summary'; const operationType = (args?.operation_type as string) || 'all'; const formattedResult = this.formatter.formatFileContext(universalResult.results, args?.filepath as string, detailLevel, operationType); // Create enhanced 3-line header with file context const lines = formattedResult.split('\n'); const sourceInfo = universalResult.enhanced ? '[⌐□_□] Searching: Claude Code + Desktop' : '[⌐□_□] Searching: Claude Code'; const actionInfo = `Target: "${args?.filepath}" | Action: File change history`; const filterInfo = operationType !== 'all' ? ` | Filter: ${operationType}` : ''; lines[0] = sourceInfo; lines[1] = actionInfo + filterInfo; return { content: [ { type: 'text', text: lines.join('\n'), }, ], }; }