Claude Historian

Instructions

Implementation Reference

• src/index.ts:375-391 (handler)

  MCP CallToolRequest handler for find_tool_patterns: delegates to UniversalHistorySearchEngine.getToolPatterns, formats with BeautifulFormatter

  case 'find_tool_patterns': {
    const universalResult = await this.universalEngine.getToolPatterns(
      args?.tool_name as string,
      (args?.limit as number) || 12
    );
  
    const patternType = (args?.pattern_type as string) || 'tools';
    const formattedResult = this.formatter.formatToolPatterns(
      universalResult.results as any,
      args?.tool_name as string,
      patternType
    );
  
    return {
      content: [{ type: 'text', text: formattedResult }],
    };
  }

• src/index.ts:207-229 (schema)

  Input schema definition for find_tool_patterns tool in ListTools response

    name: 'find_tool_patterns',
    description: 'Analyze tool usage patterns, workflows, and successful practices',
    inputSchema: {
      type: 'object',
      properties: {
        tool_name: {
          type: 'string',
          description: 'Optional specific tool name to analyze',
        },
        pattern_type: {
          type: 'string',
          description: 'Type of patterns: tools, workflows, or solutions',
          enum: ['tools', 'workflows', 'solutions'],
          default: 'tools',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of patterns (default: 12)',
          default: 12,
        },
      },
    },
  },

• src/search.ts:1061-1293 (helper)

  Core implementation in HistorySearchEngine.getToolPatterns: scans conversation history, identifies tool usage patterns and workflows, constructs ToolPattern results

  async getToolPatterns(toolName?: string, limit: number = 20): Promise<ToolPattern[]> {
    const toolMap = new Map<string, CompactMessage[]>();
    const workflowMap = new Map<string, CompactMessage[]>();
  
    try {
      const projectDirs = await findProjectDirectories();
      const limitedDirs = projectDirs.slice(0, 15);
  
      // Focus on core Claude Code tools that GLOBAL would recognize
      const coreTools = new Set([
        'Edit',
        'Read',
        'Bash',
        'Grep',
        'Glob',
        'Write',
        'Task',
        'MultiEdit',
        'Notebook',
      ]);
  
      // PARALLEL PROCESSING: Process all projects concurrently
      const projectResults = await Promise.allSettled(
        limitedDirs.map(async (projectDir) => {
          const jsonlFiles = await findJsonlFiles(projectDir);
          const limitedFiles = jsonlFiles.slice(0, 8);
  
          const projectToolMap = new Map<string, CompactMessage[]>();
          const projectWorkflowMap = new Map<string, CompactMessage[]>();
  
          // PARALLEL: Process files within project simultaneously
          const fileResults = await Promise.allSettled(
            limitedFiles.map(async (file) => {
              const messages = await this.parser.parseJsonlFile(projectDir, file);
  
              // Extract individual tool usage patterns
              for (const msg of messages) {
                if (msg.context?.toolsUsed?.length) {
                  for (const tool of msg.context.toolsUsed) {
                    // If toolName specified, only track that tool
                    // Otherwise, track all core tools
                    const shouldTrack = toolName ? tool === toolName : coreTools.has(tool);
  
                    if (shouldTrack) {
                      if (!projectToolMap.has(tool)) {
                        projectToolMap.set(tool, []);
                      }
                      projectToolMap.get(tool)!.push(msg);
                    }
                  }
                }
              }
  
              // Extract workflow patterns (tool sequences)
              for (let i = 0; i < messages.length - 1; i++) {
                const current = messages[i];
                const next = messages[i + 1];
  
                if (current.context?.toolsUsed?.length && next.context?.toolsUsed?.length) {
                  // Create focused workflow patterns
                  for (const currentTool of current.context.toolsUsed) {
                    for (const nextTool of next.context.toolsUsed) {
                      // If toolName specified, workflow must involve that tool
                      // Otherwise, workflows between core tools
                      const shouldTrack = toolName
                        ? currentTool === toolName || nextTool === toolName
                        : coreTools.has(currentTool) && coreTools.has(nextTool);
  
                      if (shouldTrack) {
                        const workflowKey = `${currentTool} → ${nextTool}`;
                        if (!projectWorkflowMap.has(workflowKey)) {
                          projectWorkflowMap.set(workflowKey, []);
                        }
                        projectWorkflowMap.get(workflowKey)!.push(current, next);
                      }
                    }
                  }
                }
              }
  
              // Also create longer sequences for complex workflows
              for (let i = 0; i < messages.length - 2; i++) {
                const first = messages[i];
                const second = messages[i + 1];
                const third = messages[i + 2];
  
                if (
                  first.context?.toolsUsed?.length &&
                  second.context?.toolsUsed?.length &&
                  third.context?.toolsUsed?.length
                ) {
                  for (const firstTool of first.context.toolsUsed) {
                    for (const secondTool of second.context.toolsUsed) {
                      for (const thirdTool of third.context.toolsUsed) {
                        // If toolName specified, 3-step workflow must involve that tool
                        const shouldTrack = toolName
                          ? firstTool === toolName ||
                            secondTool === toolName ||
                            thirdTool === toolName
                          : coreTools.has(firstTool) &&
                            coreTools.has(secondTool) &&
                            coreTools.has(thirdTool);
  
                        if (shouldTrack) {
                          const workflowKey = `${firstTool} → ${secondTool} → ${thirdTool}`;
                          if (!projectWorkflowMap.has(workflowKey)) {
                            projectWorkflowMap.set(workflowKey, []);
                          }
                          projectWorkflowMap.get(workflowKey)!.push(first, second, third);
                        }
                      }
                    }
                  }
                }
              }
            })
          );
  
          return { tools: projectToolMap, workflows: projectWorkflowMap };
        })
      );
  
      // Aggregate results from parallel processing
      for (const result of projectResults) {
        if (result.status === 'fulfilled') {
          // Aggregate individual tools
          for (const [tool, messages] of result.value.tools.entries()) {
            if (!toolMap.has(tool)) {
              toolMap.set(tool, []);
            }
            toolMap.get(tool)!.push(...messages);
          }
  
          // Aggregate workflows
          for (const [workflow, messages] of result.value.workflows.entries()) {
            if (!workflowMap.has(workflow)) {
              workflowMap.set(workflow, []);
            }
            workflowMap.get(workflow)!.push(...messages);
          }
        }
      }
  
      const patterns: ToolPattern[] = [];
  
      // ENHANCED: Create diverse patterns like GLOBAL showing related tools with workflows
      const toolFrequency = new Map<string, number>();
  
      // First pass: Calculate tool frequencies for prioritization
      for (const [tool, messages] of toolMap.entries()) {
        toolFrequency.set(tool, messages.length);
      }
  
      // Add diverse individual tool patterns (different tools, not just highest frequency)
      const usedTools = new Set<string>();
      for (const [tool, messages] of Array.from(toolMap.entries()).sort(
        (a, b) => b[1].length - a[1].length
      )) {
        if (messages.length >= 1 && !usedTools.has(tool) && patterns.length < limit) {
          const uniqueMessages = SearchHelpers.deduplicateByContent(messages);
  
          // Extract actual patterns and practices instead of generic text
          const actualPatterns = this.extractActualToolPatterns(tool, uniqueMessages);
          const actualPractices = this.extractActualBestPractices(tool, uniqueMessages);
  
          patterns.push({
            toolName: tool,
            successfulUsages: uniqueMessages.slice(0, 10),
            commonPatterns: actualPatterns.length > 0 ? actualPatterns : [`${tool} usage pattern`],
            bestPractices:
              actualPractices.length > 0
                ? actualPractices
                : [`${tool} used ${uniqueMessages.length}x successfully`],
          });
          usedTools.add(tool);
        }
      }
  
      // Add related workflow patterns for each tool (like GLOBAL's approach)
      for (const tool of usedTools) {
        // Find workflows involving this tool
        for (const [workflow, messages] of workflowMap.entries()) {
          if (workflow.includes(tool) && workflow.includes('→') && messages.length >= 1) {
            const uniqueMessages = SearchHelpers.deduplicateByContent(messages);
            // Only add if not already added and we have space
            if (!patterns.some((p) => p.toolName === workflow) && patterns.length < limit) {
              patterns.push({
                toolName: workflow,
                successfulUsages: uniqueMessages.slice(0, 10),
                commonPatterns: [workflow],
                bestPractices: [`${workflow} workflow (${uniqueMessages.length}x successful)`],
              });
            }
          }
        }
      }
  
      // If we still have space, add any remaining high-frequency workflows
      for (const [workflow, messages] of Array.from(workflowMap.entries()).sort(
        (a, b) => b[1].length - a[1].length
      )) {
        if (workflow.includes('→') && messages.length >= 1 && patterns.length < limit) {
          if (!patterns.some((p) => p.toolName === workflow)) {
            const uniqueMessages = SearchHelpers.deduplicateByContent(messages);
            patterns.push({
              toolName: workflow,
              successfulUsages: uniqueMessages.slice(0, 10),
              commonPatterns: [workflow],
              bestPractices: [`${workflow} workflow (${uniqueMessages.length}x successful)`],
            });
          }
        }
      }
  
      // Sort to prioritize individual tools, then their related workflows
      return patterns
        .sort((a, b) => {
          const aIsWorkflow = a.toolName.includes('→');
          const bIsWorkflow = b.toolName.includes('→');
  
          // Individual tools first, then workflows, then by usage frequency
          if (aIsWorkflow !== bIsWorkflow) {
            return aIsWorkflow ? 1 : -1;
          }
  
          return b.successfulUsages.length - a.successfulUsages.length;
        })
        .slice(0, limit);
    } catch (error) {
      console.error('Tool pattern search error:', error);
      return [];
    }
  }

• src/universal-engine.ts:1426-1446 (helper)

  UniversalHistorySearchEngine.getToolPatterns delegates to HistorySearchEngine.getToolPatterns

  async getToolPatterns(toolName?: string, limit?: number): Promise<UniversalSearchResult> {
    await this.initialize();
  
    const claudeCodePatterns = await this.claudeCodeEngine.getToolPatterns(toolName, limit || 12);
  
    if (!this.claudeDesktopAvailable) {
      return {
        source: 'claude-code',
        results: claudeCodePatterns as any,
        enhanced: false,
      };
    }
  
    // For tool patterns, Desktop doesn't have tool usage data, so we focus on Code
    // But we mark as enhanced if Desktop is available for future Desktop tool analysis
    return {
      source: 'claude-code',
      results: claudeCodePatterns as any,
      enhanced: this.claudeDesktopAvailable,
    };
  }

• src/formatter.ts:643-671 (helper)

  BeautifulFormatter.formatToolPatterns: formats and ranks tool pattern results for output

  formatToolPatterns(
    patterns: ToolPattern[],
    toolName?: string,
    _patternType: string = 'tools'
  ): string {
    const filter = toolName ? `"${toolName}"` : 'all';
    const header = `${robots.toolPatterns} ${filter} | ${patterns.length} patterns`;
  
    if (patterns.length === 0) {
      return `${header}\n\n{"patterns":[]}`;
    }
  
    const rankedPatterns = this.rankToolPatternsByValue(patterns);
    const topPatterns = rankedPatterns.slice(0, 8);
  
    const structured = {
      tool: toolName || 'all',
      patterns: topPatterns.map((p) => ({
        name: p.toolName,
        uses: p.successfulUsages.length,
        workflow: p.commonPatterns[0] || null,
        practice: p.bestPractices[0] || null,
        example: p.successfulUsages[0]?.content || null,
        ctx: p.successfulUsages[0]?.context || null,
      })),
    };
  
    return `${header}\n\n${JSON.stringify(structured, null, 2)}`;
  }