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

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 (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 (resolved via paths.TelemetryGateFile() in 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) relies on ReadSurfaceGate instantiated via shouldEmitReadSurface (line 70). This gate maintains state in the 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)

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)

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)

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)

The paths.New() constructor creates the NM_HOME directory structure, while p.TelemetryGateFile() returns the absolute path to 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). 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:

// 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
    })
}

// 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.
• 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 stores fingerprints and timestamps for throttling logic, managed by 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, internal/telemetry/gate.go, internal/telemetry/telemetry.go, and 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). 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, 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 (resolved via paths.TelemetryGateFile() in 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). 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}