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

> Understand Paperclip's telemetry system and learn how to disable it by setting the PAPERCLIP_TELEMETRY_ENABLED environment variable to false. Take control of your data.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: internals
- Published: 2026-08-16

---

**Paperclip's telemetry system collects operational events through a `TelemetryClient` defined in [`server/src/telemetry.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/telemetry.ts) and can be disabled by setting the `PAPERCLIP_TELEMETRY_ENABLED` environment variable to `false`.**

The [paperclipai/paperclip](https://github.com/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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:

```bash

# 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:

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

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

```bash
PAPERCLIP_TELEMETRY_ENABLED=true pnpm run some-task

```

## Key Source Files

| File | Purpose |
|------|---------|
| [[`server/src/telemetry.ts`](https://github.com/paperclipai/paperclip/blob/main/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/main/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/main/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/main/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`](https://github.com/paperclipai/paperclip/blob/main/server/src/telemetry.ts) implements buffered, batched event collection with scheduled flushing
- **CLI telemetry** uses a dedicated wrapper in [`cli/src/telemetry.ts`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/server/src/telemetry.ts) or the related CLI wrapper.