# How Telemetry Data Is Partitioned Between Local and Remote Sources in No-Mistakes

> Discover how No-Mistakes partitions telemetry data, sending high fidelity events remotely and throttling local reads to optimize performance. Learn about its dual-layer model.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: internals
- Published: 2026-07-16

---

**No-mistakes implements a dual-layer telemetry model that sends full-fidelity event data to remote servers for every state-changing command while throttling high-frequency read-only queries via a local fingerprint-based gate file that only transmits when state changes or a 10-minute heartbeat expires.**

The `no-mistakes` CLI tool partitions telemetry data between local and remote sources using a strategy that balances comprehensive audit trails with bandwidth efficiency. By categorizing operations into mutation and read-only surfaces, the system ensures complete remote visibility into critical state changes while minimizing noise from frequent status polling. This article examines the specific implementation details of how telemetry data is partitioned according to the `kunchenguid/no-mistakes` source code.

## Mutation Surfaces: Full-Fidelity Remote Reporting

State-changing commands—including `axi run`, `axi respond`, `axi abort`, and daemon-run lifecycle events—trigger comprehensive telemetry capture that prioritizes audit completeness over transmission efficiency.

### Unconditional Remote Emission

In [`internal/cli/telemetry.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/telemetry.go) (lines 21‑24), the `trackAxiSurface` function emits telemetry **unconditionally** to the remote backend on every invocation. This captures full-fidelity data including the command name, execution status, duration, and optional step/action fields. Each mutation command generates both a "pageview" and a "command" event, treating agent-driven and human-driven usage identically.

### Local Gate Storage

While remote emission is unconditional, the system maintains a local JSON-lines file at [`NM_HOME/telemetry-gate.json`](https://github.com/kunchenguid/no-mistakes/blob/main/NM_HOME/telemetry-gate.json) (resolved via `paths.TelemetryGateFile()` in [`internal/paths/paths.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/paths/paths.go)). For mutation surfaces, this file serves primarily as a local checkpoint rather than a throttle mechanism.

## Read-Only Surfaces: Sampled and Throttled Reporting

High-frequency status queries—including `axi status`, `axi home`, `axi logs`, `axi runs`, and TUI status checks—follow a strictly gated emission pattern to prevent telemetry flooding.

### Fingerprint-Based Local Gating

The `trackReadSurface` function (lines 35‑58 in [`internal/cli/telemetry.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/telemetry.go)) relies on `ReadSurfaceGate` instantiated via `shouldEmitReadSurface` (line 70). This gate maintains state in the [`telemetry-gate.json`](https://github.com/kunchenguid/no-mistakes/blob/main/telemetry-gate.json) file, storing a map of `{command → lastFingerprint, lastEmitTime}`.

Before emitting remotely, the system computes a lightweight fingerprint of the current state (e.g., a hash of run table rows or daemon PID). The gate compares this fingerprint against the stored value to detect actual state changes, ensuring redundant transmissions are suppressed.

### Heartbeat-Controlled Remote Emission

Remote emission for read-only surfaces occurs only when three conditions are met:

- Telemetry is globally enabled (`telemetry.Enabled()` returns true)
- The computed fingerprint differs from the last-sent value, indicating state change
- The `readSurfaceHeartbeat` interval (10 minutes, defined at line 26) has elapsed since the last emission

This throttling mechanism ensures that polling loops do not overwhelm the remote analytics endpoint while still capturing meaningful state transitions.

## Core Implementation Files

### Telemetry Orchestration ([`internal/cli/telemetry.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/telemetry.go))

This file contains the core helper functions `trackAxiSurface` and `trackReadSurface`, along with the heartbeat logic and data sanitization routines. The constant `readSurfaceHeartbeat = 10 * time.Minute` (line 26) defines the maximum silence period, while `readSurfaceNow` (line 31) allows deterministic unit testing via clock injection.

### Local Gate Management ([`internal/telemetry/gate.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/telemetry/gate.go))

The `NewReadSurfaceGate` function implements the `ShouldEmit` decision logic for read-only surfaces. It manages the JSON gate file structure and persistence of fingerprints and timestamps across command invocations.

### Remote Transmission ([`internal/telemetry/telemetry.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/telemetry/telemetry.go))

Low-level functions `Pageview` and `Track` (called at lines 22‑23 and 58‑59 of the CLI telemetry module) forward JSON payloads to the remote analytics endpoint. These functions respect the global `telemetry.Enabled()` flag (checked at line 62) to ensure opt-out compliance.

### Path Resolution ([`internal/paths/paths.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/paths/paths.go))

The `paths.New()` constructor creates the `NM_HOME` directory structure, while `p.TelemetryGateFile()` returns the absolute path to [`telemetry-gate.json`](https://github.com/kunchenguid/no-mistakes/blob/main/telemetry-gate.json) used by both mutation and read-only surface tracking.

## Data Sanitization and Privacy

Before remote transmission, step and action strings undergo normalization via `sanitizeAxiTelemetryStep` and `sanitizeAxiTelemetryAction` (lines 74‑89 in [`internal/cli/telemetry.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/telemetry.go)). This sanitization prevents arbitrary user data from leaking into the telemetry stream while preserving diagnostic utility for debugging command flows.

## Practical Code Examples

The following patterns demonstrate the telemetry partitioning in practice:

```go
// Mutation surface: unconditional full-fidelity tracking
func runCmd() error {
    return trackAxiSurface("run", "/repo/path", telemetry.Fields{
        "step":   sanitizeAxiTelemetryStep("run"),
        "action": sanitizeAxiTelemetryAction("approve"),
    }, func() error {
        // … actual command logic …
        return nil
    })
}

```

```go
// Read-only surface: gated, fingerprint-based tracking
func statusCmd() error {
    return trackReadSurface("status", telemetry.Fields{
        "detail": "summary",
    }, func() (fingerprint, status string, err error) {
        // Compute lightweight state fingerprint
        fp := computeRunTableFingerprint()
        return fp, "", nil // empty status → success
    })
}

```

## Summary

- **Mutation commands** (`axi run`, `axi respond`, etc.) generate unconditional, full-fidelity remote telemetry via `trackAxiSurface` while storing minimal gate data locally in [`telemetry-gate.json`](https://github.com/kunchenguid/no-mistakes/blob/main/telemetry-gate.json).
- **Read-only queries** (`axi status`, `axi logs`, etc.) use fingerprint-based sampling via `trackReadSurface` and `ReadSurfaceGate`, only emitting remotely on state changes or when the 10-minute `readSurfaceHeartbeat` expires.
- The local gate file at [`NM_HOME/telemetry-gate.json`](https://github.com/kunchenguid/no-mistakes/blob/main/NM_HOME/telemetry-gate.json) stores fingerprints and timestamps for throttling logic, managed by [`internal/telemetry/gate.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/telemetry/gate.go).
- Remote transmission respects the global `telemetry.Enabled()` flag and sanitizes sensitive fields via `sanitizeAxiTelemetryStep` and `sanitizeAxiTelemetryAction` before sending.
- Implementation spans [`internal/cli/telemetry.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/telemetry.go), [`internal/telemetry/gate.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/telemetry/gate.go), [`internal/telemetry/telemetry.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/telemetry/telemetry.go), and [`internal/paths/paths.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/paths/paths.go).

## Frequently Asked Questions

### How does no-mistakes prevent telemetry flooding from frequent status checks?

The system implements a fingerprint-based gating mechanism in `trackReadSurface` (lines 35‑58 of [`internal/cli/telemetry.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/telemetry.go)). Each read-only command computes a state fingerprint; remote emission occurs only when the fingerprint changes or when the `readSurfaceHeartbeat` interval (10 minutes) expires. This ensures polling loops do not generate excessive network traffic while maintaining visibility into state transitions.

### What data is sent to remote servers when I run a state-changing command?

Mutation surfaces trigger `trackAxiSurface`, which sends full-fidelity "pageview" and "command" events containing the command name, execution status, duration, and normalized step/action identifiers. According to lines 21‑24 in [`internal/cli/telemetry.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/telemetry.go), this emission is unconditional and occurs for every invocation of commands like `axi run`, `axi respond`, and `axi abort`.

### Where is the telemetry gate file stored and what does it contain?

The gate file is located at [`NM_HOME/telemetry-gate.json`](https://github.com/kunchenguid/no-mistakes/blob/main/NM_HOME/telemetry-gate.json) (resolved via `paths.TelemetryGateFile()` in [`internal/paths/paths.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/paths/paths.go)). It stores a JSON map tracking the last emitted fingerprint and timestamp for each read-only command, enabling the `ReadSurfaceGate` to throttle redundant remote transmissions while preserving a local audit trail.

### Can users completely disable remote telemetry collection?

Yes. All remote emission paths check `telemetry.Enabled()` (verified at line 62 in [`internal/cli/telemetry.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/telemetry.go)). When this flag returns false—typically via user opt-out configuration—both `telemetry.Pageview` and `telemetry.Track` calls are suppressed, though local gate file operations may still occur for functional consistency.