How Paperclip’s Telemetry System Works and How to Disable It

Paperclip's telemetry system collects operational events through a TelemetryClient defined in server/src/telemetry.ts and can be disabled by setting the PAPERCLIP_TELEMETRY_ENABLED environment variable to false.

The paperclipai/paperclip repository includes a built-in telemetry subsystem that records operational events and periodically flushes them to an external analytics endpoint. This article examines the core implementation, how events flow through the system, and the exact method to disable telemetry entirely.

Core Telemetry Implementation

The telemetry system centers on server/src/telemetry.ts, which exports a TelemetryClient class responsible for all event handling. The client implements a four-stage pipeline:

1. Event collection — Server components (routines, API routes, plugins) call TelemetryClient.record(event) to queue structured payloads
2. In-memory buffering — Events accumulate in a buffer to enable batch transmission
3. Scheduled flushing — A timer (approximately 30 seconds by default) triggers TelemetryClient.flush() to POST batched data
4. Graceful shutdown — A final flush on process exit prevents data loss

The CLI maintains its own thin wrapper in cli/src/telemetry.ts that forwards command-line usage data to the same underlying client, ensuring unified telemetry across both server and CLI contexts.

Event Structure and Schema

Telemetry payloads follow a generated TypeScript schema defined in packages/shared/src/telemetry/generated/paperclip-telemetry.ts. This file contains the type definitions that enforce consistent event shapes across all emission points.

Events typically include:

• Event type identifier
• Timestamp
• Source component (routine, plugin, API route)
• Contextual metadata (anonymized where applicable)

Disabling Telemetry via Environment Variable

The TelemetryClient checks the PAPERCLIP_TELEMETRY_ENABLED environment variable during initialization. When this variable is set to any falsy value (false, 0, ""), the client short-circuits:

# Disable telemetry for server and CLI

export PAPERCLIP_TELEMETRY_ENABLED=false
pnpm dev

When disabled:

• TelemetryClient.record() becomes a no-op
• The flush timer never starts
• No network requests are emitted

Explicit Disabling in Code

For programmatic control, set the variable before importing the server:

// my-setup.ts
process.env.PAPERCLIP_TELEMETRY_ENABLED = 'false';

import { startServer } from '../server/src/index';
startServer(); // Telemetry disabled for process lifetime

Verifying Disable State

Check the client's enabled status at runtime:

import { TelemetryClient } from '../server/src/telemetry';

console.log('Telemetry enabled?', TelemetryClient.isEnabled()); // → false

// No network request occurs
TelemetryClient.record({ type: 'test', data: {} });

Temporary Override

Enable telemetry for a single command without affecting shell state:

PAPERCLIP_TELEMETRY_ENABLED=true pnpm run some-task

Key Source Files

File	Purpose
[server/src/telemetry.ts](https://github.com/paperclipai/paperclip/blob/master/server/src/telemetry.ts)	Core TelemetryClient implementation with buffering and flush logic
[cli/src/telemetry.ts](https://github.com/paperclipai/paperclip/blob/master/cli/src/telemetry.ts)	CLI wrapper forwarding command usage to server client
[server/src/__tests__/telemetry-client-flush.test.ts](https://github.com/paperclipai/paperclip/blob/master/server/src/__tests__/telemetry-client-flush.test.ts)	Test suite verifying flush behavior and environment variable disabling
[packages/shared/src/telemetry/generated/paperclip-telemetry.ts](https://github.com/paperclipai/paperclip/blob/master/packages/shared/src/telemetry/generated/paperclip-telemetry.ts)	Generated TypeScript definitions for telemetry payloads

Summary

• TelemetryClient in server/src/telemetry.ts implements buffered, batched event collection with scheduled flushing
• CLI telemetry uses a dedicated wrapper in cli/src/telemetry.ts sharing the same backend client
• Disabling requires setting PAPERCLIP_TELEMETRY_ENABLED=false before process start
• When disabled, the client enters no-op mode with no timer initialization and no network activity
• All telemetry types are defined in the generated schema at packages/shared/src/telemetry/generated/paperclip-telemetry.ts

Frequently Asked Questions

What data does Paperclip's telemetry system collect?

According to the source code in server/src/telemetry.ts, the system collects operational events including routine executions, API route invocations, plugin interactions, and command-line usage patterns. The exact payload structure is typed in packages/shared/src/telemetry/generated/paperclip-telemetry.ts. Data is batched and transmitted to an external analytics endpoint via periodic flush operations.

Will disabling telemetry affect Paperclip's functionality?

No. When PAPERCLIP_TELEMETRY_ENABLED is set to false, the TelemetryClient initialization short-circuits all recording operations. The record() method becomes a no-op, and no flush timer starts. All core Paperclip features continue operating normally without telemetry emission.

Can telemetry be disabled after the server has started?

The environment variable is read during TelemetryClient initialization. Changing the variable after import has no effect on an already-instantiated client. To disable telemetry mid-process, you would need to restart the server with the variable preset, or implement custom logic around the client's isEnabled() check.

Is there a configuration file option to disable telemetry?

The source analysis shows no configuration file parsing for telemetry settings. Disabling is exclusively environment-variable driven through PAPERCLIP_TELEMETRY_ENABLED. No YAML, JSON, or other configuration formats are referenced in server/src/telemetry.ts or the related CLI wrapper.

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