# Fuzzy Search Log Analysis in DesktopCommanderMCP: Complete Usage Guide

> Learn fuzzy search log analysis in DesktopCommanderMCP. Understand editor search operations and use npm run logs:analyze to get performance metrics and recommendations.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-08-07

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/fuzzySearchLogger.ts), the system initializes the log directory automatically and maintains a header row defining all column positions ([initialization code](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/fuzzySearchLogger.ts#L28-L66)).

## 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](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/fuzzySearchLogger.ts#L10-L22)).

### 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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/fuzzySearchLogger.ts#L75-L99)).

### 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](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/fuzzySearchLogger.ts#L24-L51)).

## Using `npm run logs:analyze`

### Basic Usage

The [`package.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json) defines the `logs:analyze` script as a composite command that first compiles TypeScript sources, then executes the analysis CLI:

```bash
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:

```bash

# 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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/analyze-fuzzy-logs.js#L56-L95)).

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](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/analyze-fuzzy-logs.js#L98-L122)).

**Sample output:**

```text
=== 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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/analyze-fuzzy-logs.js#L10-L24)).
2. **Log loading**: Invokes `fuzzySearchLogger.getRecentLogs(limit)` to fetch entries without manual file handling ([lines 38-42](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/analyze-fuzzy-logs.js#L38-L42)).
3. **Parsing**: Splits tab-delimited lines into structured objects, extracting similarity scores and execution times ([lines 62-92](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/analyze-fuzzy-logs.js#L62-L92)).
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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/analyze-fuzzy-logs.js) to output JSON or CSV formats by modifying the parsing logic in lines 62-92.