Telemetry

Hankweave collects anonymous usage statistics to help improve the tool. No personal information, file contents, or prompts are ever collected.

Overview

Telemetry helps us understand how Hankweave is used in practice: which models people choose, how large hanks get, which features are adopted, and where errors cluster. It does not help us see what you’re building.

Opting Out

Any of these will disable telemetry entirely:

# Universal standard (respected by many tools)
export DO_NOT_TRACK=1
 
# Hankweave-specific
export HANKWEAVE_TELEMETRY=0

You can also disable it in your hankweave.json:

{
  "telemetry": {
    "enabled": false
  }
}

Telemetry is automatically disabled when a CI environment is detected (GitHub Actions, Travis, CircleCI, GitLab CI, Jenkins, Buildkite, Drone, AWS CodeBuild, Azure DevOps).

Precedence

If multiple settings conflict, the most restrictive one wins:

1. DO_NOT_TRACK=1 — disabled (highest priority)
2. HANKWEAVE_TELEMETRY=0 — disabled
3. CI environment detected — disabled
4. hankweave.json telemetry.enabled: false — disabled
5. Default — enabled

Privacy Principles

Every data point follows strict transformation rules before it leaves your machine:

What We DO NOT Collect

• Prompt text, system prompts, or any content you write
• File paths, directory structures, or project names
• Codon names, descriptions, or IDs (only SHA256 hashes)
• Environment variable keys or values
• Error messages (only error types like “timeout” or “rate-limit”)
• Git branch names or commit messages
• API keys or secrets of any kind
• Rig setup commands or shell output

What We DO Collect

We collect the shape of your usage, not the substance:

• Which models are used (e.g., “Claude Sonnet 4”, “Gemini 2.5 Flash”)
• Hank structure — how many codons, loops, sentinels, and which continuation modes (but not their content)
• Token counts and costs per codon and per model
• Tool usage patterns — which tools the agent called and how often
• Run outcomes — success, failure, crash, and failure types
• Feature adoption — whether checkpointing, sentinels, rigs, loops, or extensions are used
• CLI usage — which commands and flags are invoked

Events

Hankweave emits the following telemetry events:

CLI Events

Sent immediately when a CLI command runs.

Run Lifecycle

Queued during execution, sent at shutdown.

Codon Lifecycle

Queued during execution, sent at shutdown.

Other Events

LLM Analytics

Each codon completion also emits token and cost data per model, enabling aggregate analysis of model usage, cost, and latency across the Hankweave user base.

The Hank Structure

The most detailed telemetry payload is the hank structure sent with run_started. It captures the shape of every hank — never its content:

{
  "hank_hash": "a48324c7...",
  "items": [
    {
      "type": "codon",
      "position": 0,
      "id_hash": "66f62d18...",
      "model": "Claude Sonnet 4",
      "continuation_mode": "fresh",
      "prompt": { "source": "inline", "length_chars": 47 },
      "sentinels": { "count": 1, "sources": ["file"] },
      "checkpointed_files": { "pattern_count": 1 }
    },
    {
      "type": "codon",
      "position": 1,
      "model": "Gemini 2.5 Flash",
      "prompt": { "source": "file", "file_count": 1, "total_size_bytes": 2340 }
    }
  ],
  "summary": {
    "total_codons": 2,
    "loop_count": 0,
    "models_used": ["Claude Sonnet 4", "Gemini 2.5 Flash"],
    "has_sentinels": true,
    "has_checkpointing": true,
    "total_prompt_chars": 47,
    "total_prompt_files": 1
  }
}

The hank_hash changes whenever your hank configuration changes, allowing us to understand how hanks evolve over time — without knowing what they do.

User Identity

Each machine gets a random UUID on first run, stored at ~/.hankweave/telemetry.json:

{
  "clientId": "86500651-ad13-44c7-bc8d-431273253cb2",
  "createdAt": "2026-02-06T05:00:00.000Z"
}

This ID:

• Is completely random (not derived from any system information)
• Enables counting unique installations
• Cannot be linked to your personal identity
• Persists across runs until you manually delete it

To reset your identity: rm ~/.hankweave/telemetry.json

Debug Mode

To see exactly what telemetry would send without actually sending it:

export HANKWEAVE_TELEMETRY_DEBUG=1
hankweave

This will:

• Print each event to the console as [TELEMETRY DEBUG] event_name: { ... }
• Write each event as a JSON line to ~/.hankweave/telemetry-debug.jsonl

To inspect the debug log:

# View all debug events
cat ~/.hankweave/telemetry-debug.jsonl | jq .
 
# Count events by type
cat ~/.hankweave/telemetry-debug.jsonl | jq -r '.event' | sort | uniq -c | sort -rn
 
# View just run_started events (to see hank structure)
cat ~/.hankweave/telemetry-debug.jsonl | jq 'select(.event == "run_started")'

Configuration

In hankweave.json:

{
  "telemetry": {
    "enabled": true,
    "debug": false
  }
}

Environment variable overrides:

Privacy Enforcement

Hankweave enforces telemetry privacy at the type system level. When a new field is added to a codon, loop, or run type, TypeScript will produce a compile error until that field is explicitly added to the privacy map with a transformation rule (exclude, include, hash, length, etc.). This means new fields cannot accidentally leak into telemetry without a deliberate decision about how to handle them.

Related Pages

• Configuration Reference — Runtime configuration including telemetry settings
• CLI Reference — Command-line flags
• Files and Directories — Where ~/.hankweave/telemetry.json lives