mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
54 lines
2.4 KiB
Text
54 lines
2.4 KiB
Text
---
|
|
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: 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.
|
|
|
|
## 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.
|