Update: this RFC has been replaced by RFC 0038.

This document outlines the telemetry plan for Pi’s coding agent. Its intent is to track version adoption and understand user-base growth over time.

Motivation

Today, Pi’s adoption can be estimated from npm download statistics. This is a reasonable metric, but it misses installations that come from GitHub releases. It is also somewhat hard to interpret over time because dependents can skew it significantly (for example, OpenClaw).

We do not need or want extensive telemetry. A basic understanding of how many users have Pi installed and how they upgrade over time is sufficient. This should be possible without sharing user information and is no worse than what already happens today (the update check against npm).

The goal is to make the analytics publicly available on the Pi website.

Intended Behavior

Telemetry is emitted during interactive startup by piggybacking on the changelog check.

• If no stored version exists, startup is treated as a fresh install.
• If newer changelog entries exist, startup is treated as an update.

The client sends a best-effort request to https://pi.dev/install?version=<semver>. It uses a 5s timeout, does not block startup, ignores response data, and silently ignores errors.

Privacy Scope

The client-side payload only includes the version. It does not send prompts, message content, tool output, or session transcripts, and it is only sent the first time a version is bumped.

User Controls

Telemetry is skipped when offline (--offline or PI_OFFLINE=1).

Telemetry is also skipped when:

• PI_TELEMETRY overrides runtime behavior.
• If unset, enableInstallTelemetry (default: true) is used.
• Users can toggle this in /settings or settings.json.