Skip to content
harnesspmv0.5.1
Color scheme
Contrast
Color scheme
Contrast

Telemetry

In short

  • Telemetry is off. A team turns it on in harnesspm.json with a handler: a command or a file. harnesspm has no vendor code and sends nothing anywhere else.
  • Events never hold arguments, file contents or prompts. Sending never slows down or fails a command.
  • A person opts out with DO_NOT_TRACK=1, or with "telemetry": false in harnesspm.local.json.

Turn it on

{
  "telemetry": {
    "events": "all",
    "send": { "file": ".harnesspm/events.jsonl" }
  }
}

Then run npx harnesspm sync. A file handler appends one JSON line per event. A command handler, such as "node scripts/harness-events.mjs", gets each event as JSON on stdin. It runs from the project root, in a detached process, for at most 10 seconds.

The handler gets events only after a person’s sync has recorded it in harnesspm.lock.json. An agent that adds or changes a handler cannot turn it on. Review a new handler in the lock diff, like a new hook.

Events

Type When
run harnesspm run finishes a script, also when a hook runs it
mcp harnesspm mcp starts an MCP server
sync harnesspm sync writes the outputs. It lists added, removed and changed units. A sync in CI sends none.
why harnesspm why finds a unit
read The agent reads a file of a unit, or loads a file-scoped rule or a workspace’s rules by itself. Claude Code only.
skill The agent loads a skill. Claude Code only.
session A session starts or resumes

read, skill and session come from harnesspm’s own asynchronous hooks, so the agent never waits for them. Every event names units by their IDs, and the repository by its origin remote, such as github.com/acme/app. Events cover only the dependency and project layers. Units of added harnesses belong to a person and never reach the team’s handler. Events lists every field, with an example.

Send events somewhere

A handler is your own code. To post each event to a service:

// scripts/harness-events.mjs
let input = '';
for await (const chunk of process.stdin) input += chunk;
await fetch(process.env.HARNESS_EVENTS_URL, { method: 'POST', headers: { 'content-type': 'application/json' }, body: input });

For many events, prefer a file and ship it on a schedule. An OpenTelemetry Collector can tail the file with its filelog receiver, so no code runs in harnesspm.

Report your own tools

A tool of your project that is not a harnesspm script, such as yarn probe, can send its runs to the same handler:

import { reportRun } from '@tenphi/harnesspm/telemetry';

reportRun({ unit: 'app:scripts/probe', fields: { mode: 'fast' }, duration: 812, exit: 0 });

It follows the same switch, opt-outs and trust rule as harnesspm run, and never throws, prints or waits. Keep arguments, file contents and paths out of fields. Events from a project’s own tools has every field.

Opt out

Where How
Environment DO_NOT_TRACK=1
One repository "telemetry": false in harnesspm.local.json, which is never committed
Every repository on the machine "telemetry": false in ~/.harnesspm/config.json

npx harnesspm status shows whether events are sent, held or off on this machine.

Let agents report harness problems

Reporting is a rule of your own, not a harnesspm feature. Add one with npx harnesspm new rule reporting-harness-problems and say where agents should report:

# Reporting harness problems

- When a harness rule, doc, skill or tool is wrong, missing or fails, file a ticket in <your tracker>.
- Say what you tried, what happened and what you expected. Add the output of `npx harnesspm why <ID>`.
- Then go on with the task. Do not change the unit unless the user asks.

More

  • Telemetry in the specification: every field, and the trust rules for handlers.