Claude Historian

Instructions

Implementation Reference

• src/search.ts:1626-1676 (handler)

  Core handler implementation in HistorySearchEngine that finds Claude plan files (.md), reads and parses them for titles, sections, and file references, computes relevance score based on query matching in title/sections/content, sorts by relevance, and returns top results.

  async searchPlans(query: string, limit: number = 10): Promise<PlanResult[]> {
    try {
      const planFiles = await findPlanFiles();
      const plansPath = getClaudePlansPath();
  
      // Process all plan files in parallel
      const planResults = await Promise.allSettled(
        planFiles.map(async (filename) => {
          const filepath = join(plansPath, filename);
          const content = await readFile(filepath, 'utf-8');
          const stats = await stat(filepath);
  
          // Parse markdown structure
          const title = this.extractPlanTitle(content);
          const sections = this.extractPlanSections(content);
          const filesMentioned = this.extractFileReferences(content);
  
          // Calculate relevance score
          const relevanceScore = this.calculatePlanRelevance(query, title, sections, content);
  
          return {
            name: filename.replace('.md', ''),
            filepath,
            title,
            content: content.substring(0, 2000), // Limit content size
            sections,
            filesMentioned,
            timestamp: stats.mtime.toISOString(),
            relevanceScore,
          };
        })
      );
  
      // Collect successful results
      const plans: PlanResult[] = [];
      for (const result of planResults) {
        if (result.status === 'fulfilled') {
          plans.push(result.value);
        }
      }
  
      // Filter by relevance and sort
      return plans
        .filter((p) => p.relevanceScore > 0)
        .sort((a, b) => b.relevanceScore - a.relevanceScore)
        .slice(0, limit);
    } catch (error) {
      console.error('Plan search error:', error);
      return [];
    }
  }

• src/index.ts:230-255 (registration)

  Tool registration in MCP ListTools handler, defining name, description, and input schema (query required, optional limit and detail_level).

  {
    name: 'search_plans',
    description:
      'Search Claude Code plan files for past implementation approaches, decisions, and patterns',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query for plan content',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results (default: 10)',
          default: 10,
        },
        detail_level: {
          type: 'string',
          description: 'Response detail level',
          enum: ['summary', 'detailed', 'raw'],
          default: 'summary',
        },
      },
      required: ['query'],
    },
  },

• src/index.ts:393-407 (handler)

  MCP CallToolRequestSchema handler case for search_plans: extracts args, calls UniversalHistorySearchEngine.searchPlans (which delegates to HistorySearchEngine), formats output with BeautifulFormatter.formatPlanSearch, returns formatted text content.

  case 'search_plans': {
    const query = args?.query as string;
    const limit = (args?.limit as number) || 10;
    const detailLevel = (args?.detail_level as string) || 'summary';
  
    const result = await this.universalEngine.searchPlans(query, limit);
    const formattedResult = this.formatter.formatPlanSearch(
      { searchQuery: query, plans: result.results },
      detailLevel
    );
  
    return {
      content: [{ type: 'text', text: formattedResult }],
    };
  }

• src/universal-engine.ts:1537-1549 (handler)

  Delegation handler in UniversalHistorySearchEngine.searchPlans that forwards to HistorySearchEngine.searchPlans (claudeCodeEngine), returns results wrapped with source and enhanced flags.

  async searchPlans(
    query: string,
    limit?: number
  ): Promise<{ source: string; results: PlanResult[]; enhanced: boolean }> {
    // Plans are local to the machine, no Desktop integration needed
    const plans = await this.claudeCodeEngine.searchPlans(query, limit || 10);
  
    return {
      source: 'claude-code',
      results: plans,
      enhanced: false,
    };
  }

• src/formatter.ts:21-21 (schema)

  Formatter label/comment indicating handling for search_plans output formatting via formatPlanSearch method.

  plans: '[⌐▣_▣]', // search_plans