Telemetry
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 any way — an interactive command, a script, or an agent-launched MCP server — and prints a one-time notice (to the terminal when there is one, otherwise to standard error). It stays disabled in CI and whenever an opt-out is set.
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: which commands run, how long they take, whether they succeed or fail, and basic environment metadata (CLI version, Node version, OS platform). When an operation fails, we also include diagnostic detail about the error so we can debug it. For project-level analysis, ktx sends a salted hash of the project directory to group events.
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
We build telemetry around counts and coarse signals, not the contents of your
data or configuration. We don't deliberately collect your ktx.yaml, query
results, passwords, API keys, or access tokens.
The one place environment-specific text can appear is failure diagnostics: when an operation errors, the detail we record is the error as your tools reported it, which can include identifiers from your setup. If you'd rather send nothing at all, turn telemetry off using any of the options above.
Error reports
When telemetry is enabled, ktx sends PostHog Error Tracking $exception
events for CLI and daemon exceptions. Error reports help group crashes and
handled failures into PostHog issues.
Error reports can include:
- Stack frames, including function names, local file paths, line numbers, and SDK-provided source context.
- Error class names and raw error messages.
- Cause chains when the runtime exposes them.
source,handled, andfataldiagnostic fields.- Runtime version, OS, architecture, and CI fields.
- The hashed
projectIdwhen ktx knows the project.
Error reports never intentionally include:
- Secrets, credentials, API keys, tokens, cookies, signed URLs, or auth headers.
- Database URLs, connection strings, DSNs, raw argv, or raw environment values.
- SQL text, schema names, table names, or column names as explicit payload properties.
- Customer row data.
- User prompt text or raw MCP arguments.
The same opt-out controls listed above disable error reports.
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.