Telemetry

Hankweave collects anonymous usage statistics to help improve the tool. This page is the reference for that system: what identity it uses, how to turn it off, what it does and does not send, which events exist, and where the data goes. If you only want to disable telemetry, jump to Opting out; if you want to know what leaves your machine before deciding, start with Privacy principles in practice.

Identity and reset#

Telemetry gives each machine an anonymous random UUID v4, called clientId, and persists it in a local identity file. The file contains clientId and createdAt, plus optional noticeShownAt and firstSuccessAt timestamps. firstSuccessAt records the first successful hank run and is also used by the TUI's one-time star nudge.

export interface TelemetryIdentity {
  clientId: string;
  createdAt: string;
  noticeShownAt?: string;
  firstSuccessAt?: string; // Tracks first successful hank run (for star nudge)
}

The default path is ~/.hankweave/telemetry.json. Set $HANKWEAVE_CACHE_DIR to use <cache-dir>/telemetry.json instead. The path resolution lives in two small functions:

function getTelemetryDir(): string {
  const cacheDir = process.env.HANKWEAVE_CACHE_DIR;
  if (cacheDir) {
    return cacheDir;
  }
  return path.join(os.homedir(), ".hankweave");
}

function getTelemetryFilePath(): string {
  return path.join(getTelemetryDir(), "telemetry.json");
}

getOrCreateClientId() creates the UUID and file on first use, then returns the stored ID. isFirstRun() is true when the file is absent; isFirstSuccess() is true when firstSuccessAt has not been recorded. Delete ~/.hankweave/telemetry.json, or the corresponding file under $HANKWEAVE_CACHE_DIR, to generate a new identity on the next run.

See Execution directory for related local paths and First run for the first-run flow.

Opting out before sending#

Telemetry is enabled by default, but several mechanisms can disable it, and they have a fixed precedence. The resolver applies the first matching rule below; later settings cannot re-enable telemetry after an earlier rule disables it.

export function resolveTelemetryConfig(fileConfig?: TelemetryConfig): ResolvedTelemetryConfig {
  // Priority 1: DO_NOT_TRACK=1 (universal standard)
  if (process.env.DO_NOT_TRACK === "1") {
    return {
      enabled: false,
      endpoint: DEFAULT_POSTHOG_HOST,
      debug: false,
      disabledReason: "DO_NOT_TRACK=1",
    };
  }

  // Priority 2: HANKWEAVE_TELEMETRY=0 or HANKWEAVE_TELEMETRY=false
  const telemetryEnv = process.env.HANKWEAVE_TELEMETRY;
  if (telemetryEnv === "0" || telemetryEnv === "false") {
    return {
      enabled: false,
      endpoint: DEFAULT_POSTHOG_HOST,
      debug: false,
      disabledReason: "HANKWEAVE_TELEMETRY=0",
    };
  }

  // Priority 3: CI detection (cannot be overridden in V1)
  if (isCI()) {
    return {
      enabled: false,
      endpoint: DEFAULT_POSTHOG_HOST,
      debug: false,
      disabledReason: "CI environment detected",
    };
  }

  // Priority 4: Config file
  if (fileConfig?.enabled === false) {
    return {
      enabled: false,
      endpoint: fileConfig.endpoint || DEFAULT_POSTHOG_HOST,
      debug: fileConfig.debug || false,
      disabledReason: "Disabled in config file",
    };
  }

  // Resolve endpoint from env or config
  const endpoint =
    process.env.HANKWEAVE_TELEMETRY_ENDPOINT || fileConfig?.endpoint || DEFAULT_POSTHOG_HOST;

  // Resolve debug from env or config
  const debug = process.env.HANKWEAVE_TELEMETRY_DEBUG === "1" || fileConfig?.debug || false;

  // Default: ENABLED
  return {
    enabled: true,
    endpoint,
    debug,
  };

The table after the code summarizes the same precedence: DO_NOT_TRACK wins over HANKWEAVE_TELEMETRY, which wins over CI detection, which wins over the config file. CI detection treats CI=true and CI=1 as CI, and also treats the presence of GITHUB_ACTIONS, TRAVIS, CIRCLECI, GITLAB_CI, JENKINS_URL, BUILDKITE, DRONE, CI_NAME, CODEBUILD_BUILD_ID, or TF_BUILD as CI. Because this check precedes the file setting, hankweave.json cannot re-enable telemetry through this configuration path while CI is detected.

The telemetry object in hankweave.json accepts optional enabled (boolean), endpoint (URI string), and debug (boolean) properties. Additional properties are rejected by the schema.

The full object contract belongs to Hankweave JSON; the HANKWEAVE_TELEMETRY* variables belong to Environment variables. One wiring detail matters here: telemetry reads the raw telemetry key from hankweave.json through readFileTelemetryConfig(), because resolveSettings() strips that key from the effective runtime-configuration layer.

For the highest-priority opt-out, run:

DO_NOT_TRACK=1 bunx hankweave@0.10.0

Privacy principles in practice#

The telemetry source documents three transformation principles – content becomes size, paths become counts, and IDs become hashes. An eight-category privacy-handling type applies those decisions field by field; in practice, error messages become failure_type values and environment variables become counts. The header comment and the category type below are the source of those rules:

/**
 * Telemetry Types and Schemas
 *
 * Privacy-preserving types for telemetry events.
 * All types follow the principle: content → size, paths → counts, IDs → hashes.
 */

type PrivacyHandling =
  | "include" // Include as-is (safe data like model names)
  | "hash" // SHA256 hash (for IDs we want to correlate)
  | "length" // Replace with character count
  | "count" // Replace with item count
  | "count_and_size" // Replace with count + byte size
  | "type_only" // Keep type/enum, drop details
  | "exclude" // Don't include at all
  | "nested"; // Has its own privacy-preserving version

The eight field-handling categories are include, hash, length, count, count_and_size, type_only, exclude, and nested. TypeScript requires every field on Codon, Loop, and Run to appear in its privacy map; adding an unmapped field causes a compile error. The Codon map excludes name, hashes id, preserves selected configuration fields, counts file and environment-related fields, and turns prompt text into lengths or prompt-file fields into counts plus sizes. The privacy-preserving hank shape adds a SHA256 hank_hash and emits counts and hashes rather than prompt text, paths, or codon names.

For field ownership and execution semantics, see Codons and Events.

What is never collected#

The privacy maps exclude codon and loop name, runFolder, gitBranch, and serverPid. They reduce prompt text, system-prompt text, descriptions, file paths, environment variables, error messages, and rig setup to lengths, counts, hashes, types, or operation counts; raw content does not reach telemetry.

Error tracking has a separate scrubber. Before an error is sent, captureError() removes home-directory paths, API keys and tokens, KEY=VALUE patterns, and absolute paths from the error message and stack trace. This scrubber is distinct from the telemetry privacy maps.

The result is that a prompt appears as a measurement rather than its contents:

{
  "prompt": { "length_chars": "<count>" },
  "id_hash": "<SHA256 hash>"
}

See Privacy principles and Error tracking and scrubbing.

What is collected#

run_started carries a privacy-preserving hank structure: each item has a type, position, ID hash, model display name, continuation mode, prompt source and size, while the summary contains totals such as codons, loops, models, sentinels, and checkpointing.

run_completed carries a duration bucket (<1m, 1-5m, 5-15m, or 15m+), per-codon status and measurements, aggregate tool counts by name, and model-call counts by model ID. Per-codon measurements include duration, tokens, cost, sentinel measurements, and checkpoint flags.

Token usage is accumulated from token.usage events per codon and per model: input_tokens, output_tokens, cache_creation_tokens, cache_read_tokens, and total_cost. tool.result events supply tool-call and tool-error counts per codon and at run level. Every event receives hankweave_version, os, os_version, arch, node_version, is_ci, and is_compiled as common user properties.

A collected codon therefore uses measurements and labels instead of source content:

{
  "type": "codon",
  "position": "<position>",
  "id_hash": "<SHA256 hash>",
  "model": "<model display name>",
  "prompt": { "source": "<inline|file|files>", "length_chars": "<count>" },
  "checkpointed_files": { "pattern_count": "<count>" }
}

See Events for the canonical event payload schemas and Budgets for budget semantics.

Event catalog and emitter status#

The shipped TelemetryEventName union declares 26 names in nine categories. Twenty-three have emitters; loop_iteration_started, continuation_started, and $ai_span are declared-only in hankweave 0.10.0. The union and the per-category status table below show both:

export type TelemetryEventName =
  // CLI events
  | "cli_init"
  | "cli_validate"
  | "cli_cleanup"
  | "cli_run"
  | "cli_help"
  // Run lifecycle
  | "run_started"
  | "run_completed"
  | "run_failed"
  | "run_crashed"
  // Codon lifecycle
  | "codon_started"
  | "codon_completed"
  | "codon_failed"
  | "codon_skipped"
  // Loop lifecycle
  | "loop_iteration_started"
  | "loop_iteration_completed"
  // Rig lifecycle
  | "rig_setup_completed"
  | "rig_setup_failed"
  // Recovery
  | "checkpoint_created"
  | "rollback_completed"
  | "continuation_started"
  // Sentinel
  | "sentinel_triggered"
  // Budget
  | "budget_set"
  | "budget_exceeded"
  // PostHog LLM Analytics (special $ prefixed events)
  | "$ai_generation"
  | "$ai_trace"
  | "$ai_span";

Emission timing differs by event kind. Early-exit CLI events (cli_init, cli_validate, cli_cleanup, cli_help) are sent immediately through sendCliTelemetry(), which creates a temporary collector and reads hankweave.json from the current directory for opt-out. The normal cli_run event is sent immediately by the main runtime collector's trackCliEvent() after configuration resolution and collector creation. Both paths are fire-and-forget and do not block the CLI. Runtime and codon events are queued from the server event stream and batch-sent at shutdown. $ai_generation is emitted once per completed codon, or once per model when a codon used multiple models; it carries $ai_trace_id, $ai_span_id, $ai_model, $ai_provider, $ai_input_tokens, $ai_output_tokens, $ai_cache_read_input_tokens, $ai_cache_creation_input_tokens, $ai_total_cost_usd, and $ai_latency (codon duration in seconds, or undefined when duration is absent). $ai_trace is emitted at shutdown for the full run with run-level latency and an error flag.

A compact LLM analytics payload has this shape:

{
  "event": "$ai_generation",
  "properties": {
    "$ai_trace_id": "<trace id>",
    "$ai_span_id": "<span id>",
    "$ai_model": "<model>",
    "$ai_provider": "<provider>",
    "$ai_input_tokens": "<count>",
    "$ai_output_tokens": "<count>",
    "$ai_cache_read_input_tokens": "<count>",
    "$ai_cache_creation_input_tokens": "<count>",
    "$ai_total_cost_usd": "<cost>",
    "$ai_latency": "<duration-seconds>"
  }
}

The canonical payload definitions are owned by Events. The generated catalog below describes the server events that feed runtime collection; it is not a second list of TelemetryEventName values.

Network and backend#

The default endpoint is https://hw-telemetry.southbridge.ai, a self-hosted PostHog instance. Override it with HANKWEAVE_TELEMETRY_ENDPOINT or hankweave.json telemetry.endpoint. The embedded PostHog API key, phc_hDo9EY9g5eB18EYqnR2etTcEKXId7Rw971hoKQDxo5A, is public and write-only; replace it with POSTHOG_API_KEY when configuring a different backend.

Telemetry sends are fire-and-forget: a slow or failing backend does not throw or block the user. The PostHog client uses flushAt: 1 and flushInterval: 0. Immediate CLI capture() calls flush rather than batch; runtime events are queued and sent at shutdown with captureMany(). Each flush has a two-second timeout, and failures are silent.

HANKWEAVE_TELEMETRY_ENDPOINT=<endpoint-URI> bunx hankweave@0.10.0

See Troubleshooting for operational symptoms and Environment variables for the variable contract.

Debug mode without sending#

Set HANKWEAVE_TELEMETRY_DEBUG=1 or set hankweave.json telemetry.debug to true. Debug mode prints each event as [TELEMETRY DEBUG] <event_name>: { ... }, appends one JSON object per line to telemetry-debug.jsonl, and does not send the event to PostHog. The file is ~/.hankweave/telemetry-debug.jsonl by default and follows $HANKWEAVE_CACHE_DIR when set; the cache directory is created if needed.

HANKWEAVE_TELEMETRY_DEBUG=1 bunx hankweave@0.10.0

The observable line shape is:

[TELEMETRY DEBUG] <event_name>: { ... }

See Observe and debug and Environment variables.

First-run notice appears once#

After configuration resolution and before execution starts, the first run prints a boxed notice saying that Hankweave collects anonymous usage statistics. It says that personal information, file contents, and prompts are not collected, links to this page, names HANKWEAVE_TELEMETRY=0 as an opt-out, and says the notice will not be shown again. The notice is shown even when telemetry is disabled.

hasNoticeBeenShown() checks noticeShownAt, and markNoticeShown() writes it to the identity file. The source-defined text is:

const NOTICE_TEXT = `
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  Hankweave collects anonymous usage statistics to help          │
│  improve the tool. No personal information, file contents,      │
│  or prompts are collected.                                      │
│                                                                 │
│  Learn more: https://docs.hankweave.dev/reference/telemetry     │
│  Opt out:    export HANKWEAVE_TELEMETRY=0                       │
│                                                                 │
│  This notice won't be shown again.                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
`;

// =============================================================================

See First run and Identity and reset.

Error tracking and scrubbing#

Uncaught exceptions and unhandled rejections are auto-captured through PostHog's enableExceptionAutocapture: true. Manual captureError() calls add failure and correlation context such as codonStatus, runStatus, errorCode, exitCode, failureType, runIdHash, and codonIdHash.

Before sending, the scrubber removes home-directory paths, API keys and tokens, KEY=VALUE patterns, and absolute paths from error messages and stack traces. It mutates the error's .message and .stack in place. Error tracking uses the same PostHog client as telemetry and flushes at shutdown with its own two-second timeout.

A manual capture can carry safe correlation fields:

captureError(error, {
  codonStatus: "<status>",
  runStatus: "<status>",
  errorCode: "<code>",
  runIdHash: "<SHA256 hash>",
  codonIdHash: "<SHA256 hash>"
});

See Troubleshooting and Errors and exit codes.

Integration at shutdown#

The CLI creates TelemetryCollector after configuration resolution, passes it to HankweaveRuntime with setTelemetryCollector(), and subscribes the collector to the runtime's server events.

At shutdown, sendRunTelemetry() reads the final run state, composes run_started, queued events, the applicable run_completed or run_failed event, and $ai_trace, then sends the batch with captureMany() before shutting down the client. Telemetry configuration is read directly from hankweave.json; resolveSettings() removes telemetry from the effective runtime-configuration layer.

The order is:

// Pseudocode, not the implementation.
resolve config
create TelemetryCollector
runtime.setTelemetryCollector(collector)
runtime subscribes collector to server events
at shutdown:
  read final run state
  compose run_started + queued events + terminal event
  captureMany()
  client.shutdown()

See Runtime architecture, Events, and Hankweave JSON.