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

> Learn how DesktopCommanderMCP implements on-disk telemetry caching and handles disk unavailability. Discover how it ensures stability by silently dropping events when the disk is unavailable, preventing CLI crashes.

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

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/capture.ts), the `capture` utility first validates whether telemetry is enabled by reading the `telemetryEnabled` flag from the configuration manager:

```typescript
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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

```typescript
// 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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:**

```typescript
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:**

```typescript
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:**

```typescript
// 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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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.