How DesktopCommanderMCP Implements On-Disk Telemetry Caching and Handles Disk Unavailability

DesktopCommanderMCP caches telemetry events to disk before transmitting them to the telemetry proxy, silently dropping events when the disk is unavailable to ensure the CLI never crashes.

The open-source DesktopCommanderMCP project implements a resilient telemetry system that prioritizes reliability over data completeness. By leveraging on-disk telemetry caching in src/utils/capture.ts, the tool ensures that usage analytics survive network interruptions without compromising command-line performance. This article examines the caching mechanism and explains exactly how the system behaves when disk writes fail.

How On-Disk Telemetry Caching Works

The telemetry pipeline follows a write-then-transmit pattern that guarantees durability across process restarts.

Configuration Validation in capture.ts

In src/utils/capture.ts, the capture utility first validates whether telemetry is enabled by reading the telemetryEnabled flag from the configuration manager:

const isEnabled = await configManager.getValue('telemetryEnabled');
if (!isEnabled || !captureUrl) {
  return; // Early exit prevents disk and network operations
}

If telemetry is disabled or the capture URL is missing, the function returns immediately, ensuring no cache files are created and no network requests are attempted.

Persisting Events to Disk

When telemetry is active, the payload is serialized and appended to an on-disk cache file located in the configuration directory. This pattern mirrors the durable storage approach used in src/utils/feature-flags.ts for persisting feature flag data. The cache stores events as JSON entries, allowing the system to accumulate telemetry during offline periods:

// Simplified example of the caching logic
try {
  await fs.appendFile(cachePath, JSON.stringify(event) + '\n');
} catch (e) {
  // Silently ignore – telemetry must never crash the CLI
  console.debug('Telemetry cache write failed:', e);
  return; // Event dropped if disk unavailable
}

Network Transmission and Cache Cleanup

After persisting to disk, the utility attempts to POST the payload to https://telemetry.desktopcommander.app/mp/collect. Upon successful transmission, the cached entry is removed. If the network request fails, the entry remains in the cache for a subsequent retry, ensuring no data loss during temporary connectivity issues. This mechanism is invoked by utilities such as src/utils/trackTools.ts when recording tool usage events.

Disk Unavailability and Error Handling

When the filesystem becomes unavailable—whether due to read-only permissions, disk space exhaustion, or permission restrictions—the capture code handles failures without interrupting the primary CLI workflow.

Silent Failures and Graceful Degradation

If writing to the cache file throws an exception, the catch block silently swallows the error. The event is dropped, and no network request is attempted. This best-effort design guarantees that telemetry operations never block or break the host application, even when the disk is inaccessible.

Debug Logging

While user-facing operations continue unaffected, the system logs disk failures at the debug level for troubleshooting purposes. This allows developers to diagnose persistent cache issues without cluttering standard output or error streams.

Practical Implementation Examples

The following patterns demonstrate how to interact with the telemetry system and handle edge cases.

Sending a telemetry event with automatic caching:

import { capture } from './utils/capture.js';

await capture('server_opened', { success: true });
// 1. Payload written to on-disk cache
// 2. HTTPS POST attempted to telemetry proxy
// 3. On success → cache entry removed
// 4. On disk error → event silently dropped, CLI continues

Disabling telemetry to prevent disk writes:

await configManager.updateConfig({ telemetryEnabled: false });
await capture('server_opened', { success: true });
// Early return; nothing written to disk or sent over network

Handling cache write failures:

// This represents the internal error handling in capture.ts
try {
  await fs.appendFile(cachePath, JSON.stringify(event));
  await sendToProxy(event);
} catch (e) {
  // Error suppressed to prevent CLI interruption
  console.debug('Telemetry unavailable:', e);
}

Summary

• DesktopCommanderMCP uses on-disk telemetry caching in src/utils/capture.ts to persist events before network transmission
• The system checks telemetryEnabled via configManager.getValue() before attempting any disk operations
• Events are cached as JSON in the configuration directory and removed only after successful POST to https://telemetry.desktopcommander.app/mp/collect
• When disk writes fail, errors are silently caught and events are dropped without affecting CLI functionality
• The caching pattern is shared with other utilities like src/utils/feature-flags.ts for consistent durability semantics

Frequently Asked Questions

Where does DesktopCommanderMCP store telemetry cache files?

The telemetry cache resides in the application's configuration directory, alongside other persistent data managed by src/config-manager.ts. The exact filesystem path depends on the operating system's standard configuration directory conventions.

What happens to cached events when the disk is full?

If the disk is full or write-protected when an event is generated, the write operation throws an exception that is caught and suppressed. The event is immediately dropped and cannot be recovered. The system does not queue events in memory as a fallback; it relies solely on the on-disk cache for persistence between transmission attempts.

How can I disable telemetry caching entirely?

Set telemetryEnabled to false via the configuration manager. When disabled, the capture utility in src/utils/capture.ts returns early without writing to disk or attempting network requests, effectively disabling both caching and transmission. This is the same mechanism used by src/utils/trackTools.ts to respect user privacy settings.

Does telemetry caching impact CLI performance?

The impact is negligible. Cache operations are asynchronous and non-blocking. Disk I/O occurs in the background, and any latency is isolated from the main execution path to ensure responsive command-line performance, even when the telemetry proxy is unreachable.

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