Skip to Content
GuidesUsage Metrics & Privacy

Usage Metrics & Privacy

Your code, prompts, features and settings stay on your machine, in ~/.shep. The one thing Shep itself sends is a small set of usage events, so the Shep team can see which parts of Shep are used and whether runs end in merged pull requests.

Usage metrics are on by default, announced the first time you run Shep, and easy to turn off. Fields that identify you are opt-in: they’re sent only after you turn on Include my identity. This page lists everything that’s sent.

Your agents are separate: Claude Code, Codex, OpenRouter and the rest talk to their own providers under their own terms.

Turn it off

HowEffect
shep telemetry offOff. Events not yet sent are deleted
Settings → Usage metrics → Send usage metricsSame as above
Turn off on the first-run noticeSame as above
DO_NOT_TRACK=1 or SHEP_TELEMETRY_DISABLED=1Off for every Shep process that sees the variable
CI set (any value except 0 or false)Always off
Running under a test runner (VITEST, NODE_ENV=test)Always off

The environment always wins: with DO_NOT_TRACK=1 set, shep telemetry on can’t turn metrics back on.

The first-run notice "Shep collects usage metrics", listing what is sent, what is sent only with identity on, and what is never sent, with Include my identity and contact toggles and Turn off / Got it buttons

Commands

shep telemetry status # on or off (and why), identity, contact, install id, queued events, destination shep telemetry show # print the exact request body the next send would post shep telemetry off # turn off and delete queued events shep telemetry on # turn back on shep telemetry identity on # include your identity fields (off by default) shep telemetry identity off # leave them out again, including from queued events shep telemetry contact on # allow the Shep team to contact you on GitHub shep telemetry contact off

shep telemetry show replaces the project key with a placeholder, so you can paste its output anywhere.

The same switches are in Settings → Usage metrics:

Settings → Usage metrics with Send usage metrics on, identity and contact off, the number of events waiting to be sent, and where they are sent

What is sent

Every event carries:

FieldExampleNotes
distinct_idrandom UUIDThe install id, created on first run. Never derived from an account
uuidrandom UUIDPer event, so a retried send can be de-duplicated
processcli, daemon, workerWhich Shep process recorded it
shepVersion, os, arch, nodeVersion1.252.2, darwin, arm64, 22.11.0
contactConsentfalseWhether the Shep team may contact you on GitHub (off unless you allow it)
$geoip_disabletrueLocation lookup from your IP address is always off

Only with Include my identity on

Identity is off by default. When you turn it on, events also carry:

FieldSource
agentAccountHash, agentAccountSourceA SHA-256 hash of your agent account id, read from the agent’s own login file (Claude Code: ~/.claude.json; Codex: ~/.codex/auth.json). The raw id never leaves your machine
githubUsernamegh api user
githubOwnersThe GitHub users or organisations that own the repositories you added to Shep. Repository names are dropped

Identity is attached when a batch is sent, so turning it off also covers events already queued.

Events

EventPropertiesWhen
install.heartbeatagent type, names of enabled feature flags, repository count, active feature countAt most once a day
cli.commandthe command path, such as feat new, never its argumentsA CLI command runs
web.area.viewedthe area and route template, such as /feature/[featureId] (never the id)A web page is opened
feature.createdbuild mode, agent typeA feature is created
feature.run.finishedstatus, agent type, duration bucket (under-1m … over-4h)A feature run ends
pr.openedbuild modeShep opens a PR for a feature (once per feature)
pr.mergedbuild mode, whether it merged through a PRA feature’s PR merges (once per feature)
decision.answeredkind of question, where it was answered, how long it took (bucket), whether the recommended option was pickedSomeone answers an agent’s question or gate
decision.defaultedkind, deadline bucketAn agent proceeds with its recommendation at the deadline
onboarding.stepstep, completedWeb onboarding
error.unhandlederror class, a truncated hash of the top stack frameShep crashes
harness.candidate.proposedorigin, component count and kinds, whether it was auto-adoptedSelf-learning proposes a change
harness.version.adoptedorigin, component count, whether policy adopted itA learned harness version is adopted
harness.version.rejectedorigin, whether a reason was given (never the reason)A version is rejected
harness.version.rolled-backorigin, whether the previous version was restoredA version is rolled back
harness.refinement.finishedmode, status, countsA self-learning refinement ends

The harness.* events only occur when the experimental self-learning harness is on.

Never sent

Prompts, code, file paths, repository or branch names, feature titles, local ids, and error messages. Each event’s properties are declared as a fixed type in Shep’s source, so adding a content field to an event doesn’t compile.

How events are delivered

  • Every Shep process writes events to a local queue in its SQLite database. Only the long-running server (shep start or shep ui) sends them, about once a minute.
  • They go to Shep’s PostHog project in the EU region (https://eu.i.posthog.com), in batches of 20, over a plain fetch with no analytics SDK.
  • A failed batch is retried with backoff and dropped after five attempts. The queue keeps at most 5,000 events.
  • When metrics are off, the queue is emptied at the next send.
  • shep telemetry status shows where events go. If no project key is configured, it says so, and nothing is sent.

What’s next

  • Privacy policy — how the Shep team handles data.
  • Configuration — other settings and environment variables.
  • FAQ — common questions about data and accounts.