Fuzzy Search Log Analysis in DesktopCommanderMCP: Complete Usage Guide

The fuzzy search log analysis system in DesktopCommanderMCP records every editor search operation to a tab-separated log file and provides the npm run logs:analyze command to aggregate performance metrics, success rates, and diagnostic recommendations.

DesktopCommanderMCP implements a comprehensive logging mechanism that captures detailed telemetry from every fuzzy-search operation performed by the editor. This system enables developers to diagnose search performance issues, identify problematic file patterns, and optimize query accuracy through quantitative analysis of the ~/.claude-server-commander-logs/fuzzy-search.log file.

What Is the Fuzzy Search Log Analysis System?

The fuzzy search log analysis system consists of two core components: the FuzzySearchLogger singleton that persists search metadata to disk, and the scripts/analyze-fuzzy-logs.js CLI tool that parses these records to generate actionable reports.

Every time the editor executes a fuzzy search—whether through the built-in find command or programmatic file matching—the logger appends a tab-separated entry containing the query text, similarity score, execution duration, file extension, and character-level diff statistics. According to the source code in src/utils/fuzzySearchLogger.ts, the system initializes the log directory automatically and maintains a header row defining all column positions (initialization code).

How the FuzzySearchLogger Works

Initialization and Log Format

On first invocation, the FuzzySearchLogger class creates the ~/.claude-server-commander-logs/ directory and writes a header line defining the tab-separated schema. The log entries capture:

• Timestamp of the search operation
• Search text and matched result
• Similarity score (0.0 to 1.0)
• Execution time in milliseconds
• File extension of the target document
• Character codes involved in text differences

The singleton exposes three primary methods: getLogPath() returns the absolute file location, getRecentLogs(n) retrieves the last n entries, and clearLog() resets the file to header-only state (API methods).

Writing Log Entries

Each fuzzy-search call constructs a FuzzySearchLogEntry object and serializes it as a single tab-delimited line appended to the log file. The implementation in src/utils/fuzzySearchLogger.ts handles file I/O asynchronously, ensuring that search operations remain non-blocking while maintaining durable records for later analysis (logging routine).

Retrieving and Clearing Logs

Developers can access raw log data programmatically through fuzzySearchLogger.getRecentLogs(limit), which returns the most recent entries as an array of parsed objects. To reset the telemetry, the clearLog() method truncates the file back to its header state, effectively archiving or deleting historical search data (clear method).

Using npm run logs:analyze

Basic Usage

The package.json defines the logs:analyze script as a composite command that first compiles TypeScript sources, then executes the analysis CLI:

npm run logs:analyze

This default invocation analyzes the 100 most recent log entries using a 0.7 similarity threshold to distinguish successful matches from failures. The script outputs aggregate statistics including exact match percentages, average execution latency, and failure rate distributions by file extension.

CLI Options and Parameters

The underlying Node script accepts two optional flags to customize the analysis scope. Pass arguments after the double-dash (--) separator:

# Analyze 500 recent entries with a stricter 0.8 similarity threshold

npm run logs:analyze -- --threshold 0.8 --limit 500

# Short-form flags also work

npm run logs:analyze -- -t 0.6 -l 200

Parameter reference:

• -t, --threshold: Minimum similarity score (0.0-1.0) to classify a result as successful. Default: 0.7.
• -l, --limit: Number of recent log entries to analyze. Default: 100.

Understanding the Output

The analysis script in scripts/analyze-fuzzy-logs.js generates a multi-section report. The Performance Metrics section displays min, max, and average execution times, while Failure Analysis groups unsuccessful searches by similarity range and file extension to identify problematic patterns (analysis logic).

When the failure rate exceeds 10% or average execution time surpasses 100ms, the script emits Recommendations highlighting potential issues such as line-ending mismatches (CR/LF characters) or oversized search patterns (recommendations engine).

Sample output:

=== Fuzzy Search Analysis ===

Total Entries: 87
Exact Matches: 23 (26.44%)
Fuzzy Matches: 40 (45.98%)
Failures: 24 (27.59%)

--- Performance Metrics ---
Average Execution Time: 84.33ms
Average Similarity: 78.12%

--- Failure Analysis ---
Failures by similarity range:
  0-20%: 5 failures
  21-40%: 7 failures

--- Recommendations ---
⚠️  High failure rate (27.6%). Consider reviewing search text formatting.
💡 Most common character differences involve line endings (CR/LF).

Log Analysis Script Internals

The scripts/analyze-fuzzy-logs.js file performs seven distinct operations on the raw log data:

1. Argument parsing: Validates --threshold and --limit inputs using process.argv slicing (lines 10-24).
2. Log loading: Invokes fuzzySearchLogger.getRecentLogs(limit) to fetch entries without manual file handling (lines 38-42).
3. Parsing: Splits tab-delimited lines into structured objects, extracting similarity scores and execution times (lines 62-92).
4. Statistics: Computes frequency distributions for file extensions and character codes appearing in diff operations.
5. Aggregation: Tallies exact matches (similarity 1.0), fuzzy matches (above threshold), and failures (below threshold).
6. Remediation: Generates contextual hints based on detected patterns, such as whitespace normalization for frequent character code 32 (space) or 13/10 (carriage return/line feed) discrepancies.
7. Reporting: Prints formatted results and the raw log file path for manual inspection.

Summary

• The fuzzy search log analysis system captures every editor search to ~/.claude-server-commander-logs/fuzzy-search.log using the FuzzySearchLogger singleton in src/utils/fuzzySearchLogger.ts.
• Run npm run logs:analyze to compile aggregate statistics on search success rates, execution performance, and failure patterns.
• Customize analysis scope with --threshold (similarity cutoff) and --limit (entry count) flags passed after the double-dash separator.
• The script identifies common issues like line-ending mismatches and excessive query latency, providing actionable recommendations when failure rates exceed 10%.
• Clear historical logs using npm run logs:clear, which invokes fuzzySearchLogger.clearLog() to reset the telemetry file.

Frequently Asked Questions

Where are the fuzzy search logs stored on disk?

The FuzzySearchLogger persists all entries to ~/.claude-server-commander-logs/fuzzy-search.log in the user's home directory. This path is platform-agnostic and determined at runtime by the getLogPath() method in src/utils/fuzzySearchLogger.ts. You can view the raw file directly or use npm run logs:view to stream it to the console.

How do I reset or clear the fuzzy search logs?

Execute npm run logs:clear from the repository root. This command runs scripts/clear-fuzzy-logs.js, which calls the fuzzySearchLogger.clearLog() method to truncate the file back to its header row. This operation is irreversible and removes all historical search telemetry, so consider archiving the file manually if you need long-term analytics.

What similarity threshold should I use when analyzing logs?

The default 0.7 threshold (70% character match) works well for most codebases, balancing precision against typo tolerance. If you observe high failure rates in the analysis output, lower the threshold to 0.5 or 0.6 using npm run logs:analyze -- -t 0.5 to capture borderline matches. For stricter quality gates requiring near-exact matches, increase the threshold to 0.8 or 0.9.

Can I export the fuzzy search logs for external analysis?

While the repository does not include a built-in export script, the log file at ~/.claude-server-commander-logs/fuzzy-search.log uses standard tab-separated values (TSV) format compatible with Excel, Google Sheets, or pandas. Copy this file to your analysis environment, or extend scripts/analyze-fuzzy-logs.js to output JSON or CSV formats by modifying the parsing logic in lines 62-92.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}