Security and Privacy Considerations for Context Hub Telemetry: Complete Implementation Guide

Context Hub collects anonymous usage telemetry without transmitting personally identifiable information (PII) or source code, offering built-in opt-out mechanisms via configuration files and environment variables.

The andrewyng/context-hub CLI implements a privacy-first telemetry system designed to improve the content registry while maintaining strict data minimization principles. All telemetry logic resides in the cli/src/lib/ directory, with explicit safeguards against data leakage verified by comprehensive test suites.

Built-in Opt-Out Mechanisms

The telemetry system provides redundant disable methods implemented in cli/src/lib/telemetry.js (lines 5-22). The isTelemetryEnabled() helper evaluates these controls in priority order: environment variables override configuration files, which override defaults.

Environment Variable Control

Export CHUB_TELEMETRY=0 (or false) to immediately disable telemetry for the current session:

export CHUB_TELEMETRY=0
chub search "stripe"

This setting takes precedence over all other configurations (lines 5-7).

Configuration File Method

Add telemetry: false to ~/.chub/config.yaml. When parsed by cli/src/lib/config.js, this value causes isTelemetryEnabled() to return false, short-circuiting all telemetry paths before network initialization (lines 5-9).

Programmatic Status Check

Import the helper to verify telemetry state within custom scripts:

import { isTelemetryEnabled } from './cli/src/lib/telemetry.js';

if (isTelemetryEnabled()) {
  console.log('Telemetry is active – anonymized usage data will be sent.');
} else {
  console.log('Telemetry is disabled.');
}

Data Collection Scope and Limitations

Context Hub telemetry strictly limits data transmission to non-identifying metadata. The system explicitly excludes error messages, stack traces, and user content from all payloads.

Analytics Events (PostHog Integration)

In cli/src/lib/analytics.js (lines 60-71), the client.capture() method transmits only generic runtime metadata:

client.capture({
  distinctId,
  event,
  properties: {
    ...properties,
    platform: process.platform,
    node_version: process.version,
    cli_version: _cliVersion || undefined,
  },
});

This implementation sends only the client ID, platform type, Node.js version, and CLI version. No error messages or stack traces are included, as verified by tests in cli/tests/lib/analytics.test.js (lines 63-81). The posthog-node library loads lazily; if the dependency is missing, analytics are silently skipped (lines 33-45).

Sending Custom Analytics Events

When telemetry is enabled, use the trackEvent function with the setCliVersion initializer:

import { trackEvent, setCliVersion } from './cli/src/lib/analytics.js';

setCliVersion('1.4.0');

await trackEvent('custom_command', {
  command_name: 'my-tool',
  entry_id: 'openai/chat',
});

Feedback Submissions

The separate feedback endpoint (/feedback) defined in cli/src/lib/telemetry.js (lines 58-78) accepts optional user ratings with a minimal payload:

body: JSON.stringify({
  entry_id: entryId,
  entry_type: entryType,
  rating,
  doc_lang: opts.docLang || undefined,
  agent: {
    name: opts.agent || detectAgent(),
    version: detectAgentVersion(),
  },
})

Note that this excludes actual documentation content, file contents, or path information that could reveal project structure.

Anonymous Client Identification

Rather than transmitting raw machine identifiers, the CLI generates a stable, anonymous 64-character hexadecimal ID through cryptographic hashing. In cli/src/lib/identity.js (lines 66-73), the system retrieves the machine UUID (from /etc/machine-id on Linux or OS-specific GUIDs) and processes it through SHA-256:

const uuid = getMachineUUID();
const hash = createHash('sha256').update(uuid).digest('hex');
writeFileSync(idPath, hash, 'utf8');

The raw UUID never leaves the host; only the hash is stored in ~/.chub/client_id and transmitted. This identifier is cached in memory for the process lifetime to prevent unnecessary disk reads.

Network Security and Error Handling

All telemetry transmissions implement defensive mechanisms to prevent CLI hangs and data leakage. In cli/src/lib/telemetry.js (lines 48-52), each request wraps an AbortController with a 3-second timeout:

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 3000);

Network errors are caught and suppressed; the user interface never exposes stack traces or connection details. All communications use HTTPS by default (https://api.aichub.org/v1), with the underlying Node.js https module enforcing certificate validation.

Self-Hosting and Endpoint Customization

Organizations requiring data residency can redirect telemetry to internal infrastructure. The CHUB_TELEMETRY_URL environment variable overrides the default endpoint:

export CHUB_TELEMETRY_URL="https://telemetry.mycompany.com/v1"
chub get openai/chat

This routes all analytics events through corporate servers, allowing security teams to inspect traffic, implement additional filtering, or enforce geographic data boundaries while maintaining full CLI functionality.

Summary

• Opt-out by design: Disable telemetry via ~/.chub/config.yaml (telemetry: false) or CHUB_TELEMETRY=0, with logic implemented in cli/src/lib/telemetry.js (lines 5-9).
• Anonymous identifiers only: Client IDs are SHA-256 hashes of machine UUIDs, generated in cli/src/lib/identity.js (lines 66-73), ensuring no raw hardware identifiers leave the host.
• Metadata-only collection: Analytics payloads contain only platform, Node.js version, and CLI version; no source code, file paths, or error messages are transmitted.
• Secure transmission: All traffic uses HTTPS with 3-second timeouts via AbortController (lines 48-52) to prevent hanging.
• Verified by tests: Test suites in cli/tests/lib/analytics.test.js (lines 63-81) explicitly verify the absence of error_message properties and PII.
• Enterprise flexibility: The CHUB_TELEMETRY_URL variable enables self-hosted collectors for air-gapped or compliant environments.

Frequently Asked Questions

Does Context Hub telemetry collect my source code or project files?

No. The telemetry system explicitly excludes source code, documentation content, and file paths from all transmissions. As implemented in cli/src/lib/analytics.js and verified in cli/tests/lib/analytics.test.js, payloads contain only metadata such as platform type, Node.js version, and entry identifiers.

How do I completely disable telemetry for all users on a system?

Set the environment variable CHUB_TELEMETRY=0 in system-wide shell profiles such as /etc/profile or /etc/environment. This takes precedence over user-specific configuration files. Alternatively, set telemetry: false in the global config.yaml if your deployment supports system-wide configuration paths.

What is the client ID and how is it generated?

The client ID is a 64-character hexadecimal string generated by hashing the machine's UUID with SHA-256 in cli/src/lib/identity.js (lines 66-73). The raw machine identifier never leaves the device; only the cryptographic hash is stored in ~/.chub/client_id and transmitted, providing stable analytics aggregation without hardware fingerprinting.

Can I redirect telemetry to my own server for compliance purposes?

Yes. Set the CHUB_TELEMETRY_URL environment variable to your custom HTTPS endpoint before running CLI commands. This overrides the default https://api.aichub.org/v1 URL, allowing you to self-host the collector, implement additional filtering, or maintain data within specific geographic boundaries.

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