pi-telemetry-minimal

Passive Pi token telemetry: one finalized assistant turn in, one usage record out.

Writes local JSONL by default. The prescribed way to consume the stream is pi-telemetry-web, a self-hosted SQLite dashboard that receives this package's webhook payload. You can still POST the same record to any compatible org webhook.

It never records prompts, responses, tool output, command text, file contents, or code snippets.

Subagents are counted when their Pi runtime loads this extension. pi-delegate children inherit this extension through PI_CHILD_EXTENSION_PATHS, so development runs like pi --no-extensions -e . still capture delegated child turns when used with a compatible pi-delegate version. ask_questions itself does not call an LLM.

Install

pi install npm:pi-telemetry-minimal

Records

Each event is schemaVersion: 1, type: "turn_usage".

Captured:

• timestamp, turn index, assistant stop reason
• session id/file, cwd/cwd name
• model api/provider/name
• input/output/cache tokens and provider-reported cost
• labels: team/project/developer
• git metadata: root, origin, branch, commit, user name/email

Default local sink:

~/.pi/telemetry-minimal/events.jsonl

Webhook sink, when configured:

• POST one JSON record per turn
• body is the same object as local JSONL
• any 2xx is success
• optional Authorization: Bearer <token>
• 2000ms timeout by default
• best effort only: no retries, no queue, abort-aware
• failures are silent, including non-2xx responses and timeouts

Consume with pi-telemetry-web

Run pi-telemetry-web, create the first admin user, then copy the generated webhook URL and bearer token from its Settings page into ~/.pi/telemetry-minimal.json:

{
 "sinks": {
  "local": { "path": "~/.pi/telemetry-minimal/events.jsonl" },
  "webhook": {
   "url": "https://telemetry.example.com/api/telemetry/events",
   "token": "pi-telemetry-web-ingest-token",
   "timeoutMs": 2000
  }
 }
}

Existing local history can be imported in the dashboard by uploading:

~/.pi/telemetry-minimal/events.jsonl

Keep the local sink enabled unless you intentionally want webhook-only telemetry.

Configure

Full config example:

{
 "enabled": true,
 "labels": {
  "team": "platform",
  "project": "pi",
  "developer": "[email protected]"
 },
 "sinks": {
  "local": { "path": "~/.pi/telemetry-minimal/events.jsonl" },
  "webhook": {
   "url": "https://telemetry.example.com/api/telemetry/events",
   "token": "pi-telemetry-web-ingest-token",
   "timeoutMs": 2000
  }
 },
 "git": { "enabled": true, "timeoutMs": 750 },
 "warnOnError": true
}

Or env vars:

PI_TELEMETRY_ENABLED=true
PI_TELEMETRY_LOG_PATH=~/.pi/telemetry-minimal/events.jsonl
PI_TELEMETRY_TEAM=platform
PI_TELEMETRY_PROJECT=pi
[email protected]
PI_TELEMETRY_GIT=true
PI_TELEMETRY_GIT_TIMEOUT_MS=750
PI_TELEMETRY_WARN_ON_ERROR=true
PI_TELEMETRY_WEBHOOK_URL=https://telemetry.example.com/api/telemetry/events
PI_TELEMETRY_WEBHOOK_TOKEN=pi-telemetry-web-ingest-token
PI_TELEMETRY_WEBHOOK_TIMEOUT_MS=2000

Env wins over config. Boolean envs accept true/false, 1/0, yes/no, on/off.

Privacy + failure model

Webhook payloads mirror local records. If webhook is enabled, paths and git identity are sent to that backend.

Disable git metadata:

{ "git": { "enabled": false } }

or:

PI_TELEMETRY_GIT=false

Webhook delivery failures are always silent. Other failures degrade silently except for one warning when warnOnError is enabled.

Records include the assistant stopReason (stop, length, toolUse, error, or aborted) so downstream consumers can separate successful, truncated, tool-using, failed, and aborted turns without receiving error text.

Development

bun install
bun test
bun run typecheck
bun run check
bun pm pack --dry-run
PI_OFFLINE=1 bunx --bun pi --no-extensions -e . --list-models >/tmp/pi-telemetry-minimal-pi-load.out