How to Disable Telemetry in Paperclip AI: 3 Methods for Complete Privacy

Set telemetry.enabled to false in your Paperclip AI configuration file to completely disable all usage tracking and telemetry emission.

Paperclip AI includes built-in telemetry that records usage events across the server, CLI, and plugin SDK. According to the paperclipai/paperclip source code, telemetry is controlled by a single Boolean flag defined in the central configuration schema. This guide explains exactly how to disable telemetry in Paperclip AI using three different approaches.

Understanding the Telemetry System

The telemetry subsystem relies on a configuration flag located in packages/shared/src/config-schema.ts at lines 102–104. By default, telemetry.enabled is set to true, meaning telemetry activates automatically unless you explicitly opt out.

When Paperclip loads, the function resolvePaperclipConfigPath in server/src/paths.ts (lines 26–30) determines which configuration file to read. If you don't specify a custom path via the PAPERCLIP_CONFIG environment variable, it defaults to ~/.paperclip/instances/default/config.json.

The configuration loader in server/src/config-file.ts validates the schema and instantiates the telemetry client via getTelemetryClient only when telemetry.enabled is true. All call sites guard against a missing client with if (telemetryClient) … checks, so setting the flag to false stops all telemetry emission system-wide.

Method 1: Edit the Configuration File Directly

The most straightforward way to disable telemetry in Paperclip AI is to manually edit the configuration file.

Locate your config file—typically at ~/.paperclip/instances/default/config.json—and add or modify the telemetry section:

{
  "telemetry": {
    "enabled": false
  }
}

Save the file and restart any running Paperclip processes. The server and CLI will read the updated configuration on startup and skip telemetry client initialization.

Method 2: Use the Paperclip CLI Config Command

Paperclip's CLI provides a built-in config command that modifies values using the shared schema. This approach avoids manual JSON editing and ensures valid syntax.

Run the following in your terminal:

paperclip config set telemetry.enabled false

This command writes the value directly to the same configuration file that the runtime reads, located via resolvePaperclipConfigPath. After execution, restart Paperclip to apply the change.

Method 3: Verify Telemetry Is Disabled Programmatically

To confirm that telemetry is fully disabled, you can inspect the telemetry client status in code:

import { getTelemetryClient } from "@paperclipai/shared/telemetry";

const client = getTelemetryClient();
console.log("Telemetry client present?", !!client); // should print false

Alternatively, check process logs—no "telemetry" messages should appear after the configuration change. The getTelemetryClient function in server/src/telemetry.ts returns null when the flag is disabled, and all logging operations silently skip execution.

Configuration File Locations and Environment Variables

Paperclip AI resolves configuration through a specific hierarchy:

Source	Priority	Details
PAPERCLIP_CONFIG environment variable	Highest	Custom path to config.json
Default path	Fallback	~/.paperclip/instances/default/config.json

The resolvePaperclipConfigPath function in server/src/paths.ts implements this resolution logic. If you run multiple Paperclip instances or use non-standard directory structures, set PAPERCLIP_CONFIG to ensure your telemetry preference applies consistently.

Key Source Files for Telemetry Control

Component	File Path	Role in Telemetry Disable
Configuration schema	packages/shared/src/config-schema.ts	Defines telemetry.enabled with default true
Config path resolver	server/src/paths.ts	Locates which config.json to load
Config loader	server/src/config-file.ts	Parses and validates configuration
Telemetry client factory	server/src/telemetry.ts	Returns client only when enabled
CLI config command	cli/src/commands/configure.ts	Provides config set interface

Summary

• Manual edit: Modify telemetry.enabled to false in ~/.paperclip/instances/default/config.json
• CLI command: Run paperclip config set telemetry.enabled false for programmatic updates
• Environment override: Use PAPERCLIP_CONFIG to specify custom configuration paths
• Verification: Check that getTelemetryClient() returns null or observe absent telemetry logs

All three methods achieve the same result: the telemetry client remains uninitialized, and Paperclip AI emits no usage data.

Frequently Asked Questions

What data does Paperclip AI telemetry collect when enabled?

The source analysis does not specify exact event types, but the telemetry client is instantiated via getTelemetryClient and used throughout the server, CLI, and plugin SDK. When enabled, it likely captures usage patterns, error reports, and performance metrics to inform product development.

Will disabling telemetry affect Paperclip AI functionality?

No. The codebase guards all telemetry calls with null checks (if (telemetryClient) …), so operations continue normally without the client. No features degrade or change behavior when telemetry is disabled.

Can I disable telemetry for specific Paperclip instances only?

Yes. Each instance uses its own configuration directory under ~/.paperclip/instances/{instance-name}/config.json. Set telemetry.enabled to false in the specific instance's config file, or point PAPERCLIP_CONFIG to different files for different contexts.

Does the paperclip config set command validate my input?

Yes. The CLI command in cli/src/commands/configure.ts works with the shared schema from packages/shared/src/config-schema.ts, ensuring that values like telemetry.enabled conform to expected types (Boolean) before writing to the configuration file.

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