ktx/docs-site/content/docs/community/telemetry.mdx

---
title: Telemetry
description: Understand what usage telemetry ktx collects and how to opt out.
---

**ktx** collects aggregated usage telemetry so maintainers can see
which commands work, where setup fails, and which parts of the data-agent
workflow need improvement. Telemetry is opt-out: it turns on the first time you
run **ktx** in an interactive terminal, which prints a one-time notice. From
then on the same install also reports background activity that has no terminal
of its own, such as the local MCP server your agent calls. It stays disabled in
CI, whenever an opt-out is set, and until that first interactive run has shown
the notice.

## Opt out

Use any of these mechanisms to disable telemetry:

| Mechanism | Effect |
|-----------|--------|
| `export KTX_TELEMETRY_DISABLED=1` | Disables telemetry for the shell and child processes |
| `export DO_NOT_TRACK=1` | Standard do-not-track environment variable |
| `CI=1` | Automatic in CI |
| Edit `~/.ktx/telemetry.json` and set `"enabled": false` | Persistent for the machine, including the MCP server |

## What we collect

High-level signals only: which commands run, how long they take, whether they
succeed or fail, and basic environment metadata (CLI version, Node version, OS
platform). For project-level analysis, **ktx** sends a salted hash of the
project directory — never the raw path.

When an agent reaches **ktx** through MCP, we also record the connecting client
tool's self-reported name and version (for example Claude Desktop, Cursor, or
Cline) so we can see which agents people use **ktx** with. That describes the
tool, never you or your data.

## What we never collect

- File paths, hostnames, environment variable values, or command arguments
- `ktx.yaml` contents, connection passwords, API keys, or tokens
- Schema names, table names, column names, SQL text, or query results
- Error messages or stack traces
- Git remote URLs, Git user email, OS user, or hostname

## Storage and retention

Telemetry is sent to PostHog, a third-party product-analytics service used by
the **ktx** maintainers. Raw event data is retained for 90 days. Aggregated
counts may be retained indefinitely.