Skip to content

Telemetry ​

Telemetry is the harness measuring itself: one append-only stream per subject, plus a family of readers that walk the transcripts, settings files, tag frontmatter, and lesson store Claude Code already wrote. Almost every reader is post-hoc, so nothing about a module, a gate, a nudge, or a workflow has to be instrumented before it runs, and a scan reaches back over sessions that finished long before you asked. It exists because the alternative was tried twice and rebuilt both times – a live PostToolUse emitter credited a module with the context growth that followed it and overstated the true footprint by a median of 4.1x, and a specced emit-line-per-guard design was dropped before it shipped because it edits every gate, cannot see a gate it did not edit, and reports nothing for the exact case worth catching, a gate that dies before its own emit line runs.

Only one of the readers here, scan-usage.nu, takes a module as its subject. The rest measure sessions, gate health, workflow spend, turn end nudges, file reads, the tag pool, the lookup layer, the clock, whether a .claude/rules/ file ever visibly changes anything, whether corrections are actually falling over time, and whether the lessons those corrections produce ever surface again. Telemetry is a harness-wide job rather than a module profiler. It is also a local module, not a project part: it installs global into ~/.claude/telemetry/ through harness local, is tracked in its own ~/.claude/harness-local.nuon store rather than the shared install registry, and ships no settings fragment on purpose. These are readers you run on demand, and wiring one to a hook event is a separate, deliberate act.

In Practice ​

Pricing a module's footprint. You want to know whether a skill or script is earning its context cost.

nu ~/.claude/telemetry/scan-usage.nu report

An example outcome. A table grouped by module, each row carrying its class, fire count, and average / min / max token figure. If nothing has been scanned yet it says so and points at scan-usage.nu backfill rather than printing an empty table.

Pricing a workflow's real spend. A fan-out just finished and you want to know what its subagents actually burned, not the small tool_result it left behind in the main transcript.

nu ~/.claude/telemetry/scan-agents.nu last

An example outcome. A per-agent table for the newest run, sorted by billed cost highest first, then a total block: billed input-token equivalents labelled as the comparable figure, with the four raw columns – in, out, cache-write, cache-read – broken out beneath it.

Asking how much is uncosted, without changing anything. notify answers the same question but it also emits into the agents stream and moves its watermark, which makes it useless as a count.

nu ~/.claude/telemetry/scan-agents.nu pending

An example outcome. A bare integer on stdout and nothing else, the number of workflow runs never costed. It is the read half of notify with none of the writing, which is what lets the turn end nudge layer ask whether there is anything worth a word. Anything going wrong prints 0, so the caller reads a failure the same way it reads quiet.

Measuring the turn end nudge layer. The nudge part speaks at the end of a turn, and the question that matters is whether the agent did anything about it.

nu ~/.claude/telemetry/scan-nudges.nu report

An example outcome. The fire count and how many sessions it spans, split into blocked against spoke only, hook errors counted apart, then a per-client table (wiki, mod-doc, plan-close, handoff-cleaner, backlog, telemetry-spend, nudge), what the agent did next, and the false-hit rate. It is a pure reader over transcripts, so it started full rather than starting a wait: the six hand rolled Stop hooks the nudge part replaced had been firing for weeks and every one of those fires was already on disk.

Asking what the layer decided not to say. A suppression leaves no trace in a transcript, so it comes off the one live stream in this module.

nu ~/.claude/telemetry/scan-nudges.nu suppressed

An example outcome. Two tables, suppressions per entry and suppressions per reason – refire (nothing has moved since that entry last spoke), empty (a ledger entry whose module is holding nothing), capped (it ranked below max_per_turn). On a box where the stream has never been written it says the stream only holds data from the day the nudge part shipped, rather than printing a zero that reads like a measurement.

Checking whether the gates are healthy. You want to know which guards are catching things and which have quietly broken.

nu ~/.claude/telemetry/scan-guards.nu report

This opens with the record, bounce, error, and session counts, then leads with whatever has errored in the last seven days, because a broken gate letting everything through is more urgent than a lifetime bounce count.

Checking whether stored lessons are actually landing. hits only moves when lessons.nu hit is called, which almost nothing does.

nu ~/.claude/telemetry/scan-lessons.nu report

An example outcome. Stored lessons against how many have ever surfaced, the total injections across however many transcripts were scanned, then never-surfaced, surfaced-but-unconfirmed, and confirmed-at-least-once beneath it. The gap it closes is not theoretical: 43 of 251 stored lessons had ever been hit, roughly 17 percent, and on 2026-09-04 distill's never-hit list offered to delete 20 of the 44 harness lessons, including gate G-fw-1 and the style-lint apostrophe rule, both of which had surfaced that same day.

Checking whether a rules file is pulling its weight. A .claude/rules/ file is eager, injected on every turn of every session whether it is relevant or not, so the open question is never whether it loaded, only whether anything ever came of it.

nu ~/.claude/telemetry/scan-rules.nu report

An example outcome. One row per rule file, cited-first: how many main sessions and how many subagent windows paid for it, how many turns cited it back and when, and its token cost. dead narrows that same table to the rules cited zero times – a shortlist to re-read and tighten, never a delete list, since a rule can be obeyed silently. cost prints the per-window token total across every rule file, the figure that is owed whether or not a session ever needed any of them.

Closing out a session or writing a handoff. Rather than re-deriving what happened by reasoning back over the conversation, ask for the numbers.

nu ~/.claude/telemetry/session-ledger.nu current --json

An example outcome. One joined record: wall minutes, turns, tool use, which modules fired and their token cost, guard bounces, hook spans if the trace was running, and workflow or task-agent spend, keyed off CLAUDE_CODE_SESSION_ID. The --json face is the real interface here and the printed table is the human courtesy.

Catching a hook that has been dead for a fortnight. The static audit answers what should fire, off the settings JSON alone with nothing running.

nu ~/.claude/telemetry/hook-trace/audit-hooks.nu --all

An example outcome. This is what found the DEAD WRAPPER fault. The global probe-session.nu registrations had been wrapped through a trace.nu path that stopped existing when hook-trace/ moved under modules/telemetry/ on 2026-08-13, so the hook errored on every session for a fortnight while the audit still reported clean, because it resolved every wrap back to the original command before checking anything. Both harness-hooks.jsonl and harness-session.jsonl stopping dead on that exact date is the corroborating evidence.

Reading a stream yourself. The spine is the plain interface, and the right answer when a scanner's own report does not cut the data the way you want.

nu ~/.claude/telemetry/telemetry.nu query usage --where module==memory

An absent stream comes back as an empty table rather than an error. Note --where is one exact string equality – no !=, no >, and no second filter – so tokens==900.0 misses a stored 900.

Post-hoc, and the Three Exceptions ​

frameworks/TELEMETRY.md is blunt about it: measure post-hoc, off what is already on disk, do not emit per event. A live emit is only correct when the fact genuinely is not recoverable afterwards, and you have to prove that before you write one. Three things here clear that bar.

live emitterwriteswhy it cannot be post-hoc
hook-trace/trace.nuharness-hooks.jsonlClaude Code files no record for a hook that fires and passes – 518 real fires against 16 attachments on one measured session – so duration and silent successes have no source at all.
probe-session.nuharness-session.jsonlWhether SessionEnd fired is a fact about a hook that may have produced nothing, and the cause (source / reason) exists only in the payload.
.claude/nudge/nudge.nuharness-nudges.jsonlA suppression – the injector evaluating a candidate and then deciding to stay quiet – is filed nowhere. The hook trace would show the hook ran and never what it decided.

The nudge emit is the narrowest of the three and deliberately so. It fires only when a candidate was actually evaluated and then held back, never on a quiet turn, so a normal session writes zero lines. It resolves the spine through HARNESS_NUDGE_SPINE (default ~/.claude/telemetry/telemetry.nu) and returns silently when that file is not there, so a project without telemetry installed globally simply records nothing rather than erroring at the end of every turn. The stream starts the day the nudge part ships. It cannot be backfilled the way the fires can, and scan-nudges.nu says so in words rather than printing a zero.

Reading a Hook Attachment ​

Four attachment types carry the whole hook picture, and three of them mean genuinely different things. Conflating them is the single easiest way to produce a wrong number here, so scan-nudges.nu and scan-guards.nu both count them apart.

attachmentwhat it meanswho reads it
hook_successthe hook merely RAN. Every Stop hook that runs files one, {} on stdout is enough.scan-clock.nu keys its clock fires off this record. scan-nudges.nu deliberately ignores it.
hook_system_messagethe hook SPOKE, non-blocking. The text is the whole record and it carries no command, so it cannot be attributed to a specific hook by path.scan-nudges.nu, which is why spoken fires are matched off the message's leading words.
hook_blocking_errorthe hook BLOCKED, it exited 2 and stopped the turn or the tool call. The command is nested one level down under blockingError.scan-guards.nu counts these as bounces, scan-nudges.nu as blocks.
hook_non_blocking_errorthe hook itself FELL OVER and is letting everything through. The command sits flat on the record.Both, counted apart from the above, never added to it.

hook_success is not a fire. Counting it reads a silent hook as a busy one – it was 1002 of the first 1237 rows scan-nudges.nu reported before that was fixed. And because a spoken fire carries no command, it is attributed off the opening words of the message, anchored to the start and never searched for loose. A loose text match would find finn quoting a nudge back and an agent repeating it, which is exactly the trap scan-clock.nu names for time & date:.

Where the Stores Live ​

The streams moved out of ~/.claude/ and into the harness's own store/telemetry/ in the T5.2 pass on 2026-08-30, gitignored so runtime data never commits. Because a tracker has two copies on disk – one in the repo, which is what the live hooks actually run, and one at ~/.claude/telemetry/, which is what a hand run reaches for – and neither can work out where the harness lives from its own position, the address is stamped once into a pointer file that all of them read back from a fixed path.

harness local writes the pointer when it installs this module, merging rather than overwriting, and the same install carries the named store files across in one step. A file already at the destination is left alone and its old copy is reported rather than merged, because two append-only logs of one stream cannot be reconciled by anything but a human. A missing or unreadable pointer reads as absent rather than throwing, so an unstamped box keeps writing to ~/.claude exactly as it always did.

Every tracker carries its own copy of the store-dir def and installer/src/stores/telemetry-dir.ts is the TypeScript twin of the same three steps. They have to agree. A manager reading one store while the scanners write another is the exact failure the pointer exists to prevent.

Not everything trace.nu writes moved with the rest. harness-rewrites.nuon is written by trace.nu, so it looks like ours, but it is a manager store that installer/src/models/rewrites.ts reads at ~/.claude, and the settings merge depends on the pair agreeing. It stayed put, resolved through a separate home-dir def rather than the spine's store-dir, and it honours HARNESS_REWRITES. The pointer itself is a manager config for the same reason: it names the store, so it cannot live inside it.

The Streams ​

Every tracker that emits writes into its own append-only stream, one JSON object per line at <dir>/harness-<stream>.jsonl.

streamwritten byanswers
usagescan-usage.nuwhich module fired, and its token footprint
agentsscan-agents.nuwhat a workflow's or a Task call's subagents actually burned
guardsscan-guards.nuwhich gate bounced or errored, and on what
readsscan-reads.nuwhich files a session pulled, class splitting main from subagent
clockscan-clock.nuday-change against same-day fires, event fan-outs, and now.nu calls bucketed by flag
nudges.claude/nudge/nudge.nuone line per SUPPRESSION only, { session, entry, class, why, count }. Everything else about the nudge layer is read post-hoc by scan-nudges.nu.
sessionprobe-session.nudid a SessionStart get a matching SessionEnd, and why
hookshook-trace/trace.nuwhat actually fired at runtime, how long it took, whether it blocked
metamodules/memory/store/lessons.nu adda lesson-add outcome, add against reject, the rate between them being dedup pressure

The emitting scanners each keep a watermark beside their stream, keyed by session or run id, so a re-run only reads what a session grew by, a still-growing session gets picked up again, and --all forces the full re-read. scan-reads.nu carries two key shapes in one watermark, a session id for a main transcript and <session>::<agentId> for an agent file.

Two things sit outside that shape. scan-tags.nu banks a dated snapshot to harness-tags.nuon, a NUON state file rather than a stream, capped at the last twelve records so drift has something to diff against. And the meta stream is the one exception to going through the spine: lessons.nu add appends to harness-meta.jsonl inline, wrapped in a try that swallows everything, so the memory store never grows a hard dependency on this module and a lesson add can never fail because a tracker is missing.

scan-nudges.nu, session-ledger.nu, correction-rate.nu, scan-context.nu, scan-lookups.nu, scan-rules.nu, and hook-trace/audit-hooks.nu bank nothing at all and carry no watermark. Every input they join is already append-only on disk, so a cached roll-up would only add a staleness class and a watermark to get wrong, and a re-run costs nothing. scan-lessons.nu sits beside them for report, dead, and loud, but not for sync, the one command anywhere in this set that writes – and what it writes is a row in the lesson store, not a telemetry stream. Nothing rotates or prunes any stream, and the store is global and shared across every project on the box, so put your own project field in a record if you want to split one back out later.

What Runs On Its Own ​

Almost nothing here is wired. The module ships no settings fragment, and the trackers are readers you invoke. Two entries are registered in this repo's own .claude/settings.json:

triggercommandbehaviour
SessionStartscan-usage.nu scan --quietsilent unless it actually banks something
Stopscan-agents.nu notifyprints the spend of any run that finished since the last turn, through { systemMessage }, and scans it in the same pass

Both run from the repo path, not the installed copy. Each command is ${CLAUDE_PROJECT_DIR}/harness/modules/telemetry/<script>.nu, so what fires is the source tree and the ~/.claude/telemetry/ copy is only what a hand run reaches for. Worth knowing before you edit one and wonder which half you changed. Both are observers that fail open. Only notify bails when HARNESS_HOOKS_OFF is 1; scan-usage.nu scan carries no such check today.

notify is also superseded as a Stop hook. The nudge layer carries a telemetry-spend entry that calls scan-agents.nu pending for its count and points at notify as the thing to run by hand, but that entry ships enabled: false because telemetry installs into ~/.claude/ rather than into a project, so arming it in this repo is finn's call. Until it is armed, the old hook keeps running and nothing double fires.

hook-trace/trace.nu is a deliberate diagnostic mode you turn on with wrap and off with unwrap, never an always-on tracker. While it is wrapped, a harness install or harness doctor --fix may not recognise the wrapped entries as wired and can re-add unwrapped twins beside them, so both fire.

What It Can and Cannot Tell You ​

Footprint and spend are different questions. scan-usage.nu prices a module's footprint, the content it actually put in the context window. scan-agents.nu prices a workflow's spend, what its agents burned on their own transcripts. A fan-out that reads as one small tool_result in the main transcript is only fully priced by the second; the first is structurally blind to it.

A bounce and an error are never the same signal. A bounce means the gate did its job and stopped a tool call. An error means the gate itself fell over and is silently letting everything through. Adding them together reads a broken gate as a busy one.

A bounce rate has no honest denominator. Claude Code only files an attachment when a hook produces output, errors, or blocks. Measured on one real session, 518 hook fires against 16 attachments, roughly 97 percent left no record. scan-guards.nu can answer how often and over what, never out of how many; the denominator only exists once trace.nu has been wrapped and run.

A false hit is a guess that was wrong, not a bug. scan-nudges.nu calls a fire a false hit when the session carried on for two or more further real user turns, since the wrap-up signal that triggered it had clearly misread the moment. The threshold is a flag (--false-hit-turns) and not a constant, because there is no right answer to it – one extra user turn could be finn answering the nudge itself.

Suppression counts start from zero and mean it. The fires backfill, the suppressions cannot. A low suppressed count on a fresh install is an absence of history, not evidence that nothing is being held back.

Surfacing is not usefulness. scan-lessons.nu only tells you the recall hook's word overlap matched a prompt and injected a lesson, never whether the lesson was any good. A lesson that has never once surfaced is at least a fact about the lesson rather than about anyone's bookkeeping, which is what dead is for. The id is matched as text, so a renamed lesson reads as two.

A citation is a rule reasoned about out loud, not a rule obeyed. scan-rules.nu counts LOADED off the structured instructions attachment, exact, and CITED off an assistant turn naming the file, which only catches a rule the model talked about. A rule cited zero times is a shortlist to re-read and tighten, never proof that nobody follows it.

A trend needs a sample, and a falling number can mean the habit lapsed. correction-rate.nu will not call a verdict under its minimum event count, and it carries total adds beside the headline in every view, because corrections falling while capture falls in step is the harness looking better by being used less. Its newest weekly row is the week you are standing in and is partial by construction, so the report says so.

Wall time is not work time. session-ledger.nu's minutes figure is first record to last, so a session left open overnight reads as hours it never did; turns rides beside it as the honest measure.

A passive injector is named by what it wrote. INJECTOR_SIGS in scan-usage.nu matches the opening of an injected block, so reword or re-wrap one and it drops to a bare event name until the table gains a row.

Only a Read counts as a read, except in one place. A file pulled through cat or sed in a Bash call lands as loose stdout with nothing marking it as a file, so a bash-first session reads as having read nothing in scan-context.nu and scan-lookups.nu. scan-reads.nu is the one that does count those, parsing the path back out of the command string, and it keeps that approximate half reported apart from the exact one rather than merging the two.

The Spine ​

telemetry.nu ​

The engine – three subcommands. emit appends one stamped JSON line per event, emit-many batches a whole scan's rows into a single append (a per-record process spawn would never finish a backfill), and query reads a stream back as a table, returning an empty table rather than an error when nothing has been written. The caller passes the record and the spine only adds time. Both write paths swallow bad input on purpose: an empty or unparseable --json returns quietly having written nothing.

The Scanners ​

scan-usage.nu ​

Module footprint – walks a finished transcript once and attributes a token figure to every module fire in it: a skill's body (the text block sharing a promptId with its launch stub), a script's stdout, a workflow's return, and a passive injector's hook output. Tokens are estimated at four characters per token, rough on purpose since the badge it feeds is three buckets. The INJECTOR_SIGS table is the one honest handle on which injector wrote a passive block, since a passive injector names itself only by the event it fired on – hookName is SessionStart:startup, never the script. The table is walked top down and the first prefix hit wins, and it keeps pre-wrap opening lines beside their XML tags (<lessons>, <context>, <handoff>) so a transcript written before the wrap still attributes. An injector that emits several blocks is named by whichever lands first.

scan-agents.nu ​

Workflow spend – prices what a workflow's subagents actually burned, reading the per-agent transcripts under <session>/subagents/, the piece a main-transcript walk structurally cannot see. Raw tokens are weighted into a billed figure (output 5x an input token, cache-write 1.25x, cache-read 0.1x, off token-weights.nuon beside the script with the same ratios baked in as a fallback) so runs compare against each other rather than read as an invoice. It covers both halves, class: "agent" for a Workflow fan-out and class: "task" for a plain Agent call, and only the task half rolls up per part, since a Workflow run names only a wf_ id. pending is the pure-read count, notify is the wired half and the one place here that checks HARNESS_HOOKS_OFF.

scan-guards.nu ​

Guard bounces against errors – reads the two attachment types Claude Code files for a hook that blocked or fell over, with no line added to any guard script and no wrapping, so it works retroactively over every session ever recorded. report leads with what is erroring in the last seven days, trend shows the daily count so a repair landing is visible against a gate going quiet, and reasons <guard> lists what one gate actually bounces on most.

scan-nudges.nu ​

The turn end injector – what actually spoke at the end of a turn, whether it blocked, and what the agent did next, per client. A pure post-hoc reader with no watermark and no emit of its own, which is the whole of why it needed no wiring: a re-run is free and cannot double count. Fires are attributed off the script name in the hook record, never the emitted wording, so a reworded reason is still attributed and the six retired hook names are kept in the table on purpose – that is what makes the backfill work. backlog-nudge.nu is tested before the arbitrated nudge.nu because a loose test for the latter would eat the held-back client and report it as the new layer. Outcomes are three coarse buckets read off the first assistant record after the fire – asked (an AskUserQuestion call), acted (any other tool call), answered (no tool call), plus stopped when the session ended there – because a finer read would be a guess dressed as a measurement. suppressed reads the live stream on its own.

scan-reads.nu ​

Which files got pulled – per session and per subagent, with a subagent as its own row that is never folded into its parent, because a subagent read lands in the subagent's window and not in the main one. Two halves kept apart because one is exact and one is not: a Read takes its path off input.file_path, while a cat / head / tail / sed -n in a Bash or PowerShell command has its path parsed back out of the command string and its size split evenly across a command naming several files. The pairing walks the tool_use block rather than the result, since a subagent transcript files a flat string result with no path in it at all. Every report prints the split so you can see how much of a number rests on the parsed side.

scan-clock.nu ​

Is the clock actually working – counts what the clock context part injected and how often now.nu got reached for, off transcripts already on disk. It splits fires into day_change (the injected line carried a date), same_day (a bare time), and event (a day change that also fanned events.nuon), plus call, a Bash now.nu invocation bucketed by the flag it carried, which is the call-site handle without planting anything to trace. It matches the hook's own hook_success record and never the injected line as loose text.

The Readers ​

Where the scanners price cost and gate health, these read what a session's context contained, whether the harness's own conventions are holding, and whether the lessons it wrote down surface again. None of them writes a telemetry stream.

correction-rate.nu ​

The getting-better north-star – the one reader that says whether the harness is improving rather than what it costs. It reads the lesson store's source field (a lesson banked as corrected is one finn had to correct), normalises corrections per 10 sessions so a busy week does not read as a bad one, and takes its session denominator from the transcripts rather than the session probe, which has only run since 2026-08-04 and would silently shorten the whole history. report prints the weekly table plus a verdict, sources splits the store by source, list names every corrected lesson.

scan-lessons.nu ​

Lesson surfacing, not lesson correctness – walks every transcript for the - [domain/id] lines the recall hook prints, off the attachment.stdout record its injection lands in, and rolls each stored lesson up to how many times it surfaced and when it last did. It exists because every staleness call in the store was keyed on hits, a counter only lessons.nu hit moves. dead lists lessons that have never surfaced past a grace window (--grace, default 30 days, matched to lessons.nu's own drop age so the two passes agree on what is too new to judge), loud lists lessons the hook keeps showing that nobody ever confirmed, and one <domain/id> prints a single lesson's history. The two failures used to look identical and mean opposite things: never surfaced means nothing routes to the lesson at all; surfaced-but-never-hit means the agent keeps seeing it and never confirms, which is either a lesson that is not actionable or proof that hit is a dead mechanism. sync is the one writer, additive and idempotent, and it writes back into the lesson store rather than a stream, because telemetry is a local module and the memory store installs into real projects, so a hard edge either way would break every project that has lessons and no telemetry.

scan-rules.nu ​

Whether a .claude/rules/ file ever changes anything – a rules-tier file is eager, paid on every turn of every session whether it is relevant or not, so cost is never the open question, effect is. LOADED is the exact half, read off the attachment.type == "instructions" record, whose files list carries one { path, type, content } per injected rule file – deliberately not a text match on the rendered Contents of <path>: line, which also turns up in an injector's own stdout and in an agent describing the mechanism, the same trap scan-clock.nu documents for time & date:, and the one this script's first pass fell into, counting an injector log line as a rule load. CITED is the approximate half, an assistant turn naming the file as rules/<name>, which catches a rule the model reasoned about out loud and misses every rule it simply obeyed, so a rule cited zero times is a review candidate and never proof of a dead one. Main sessions and subagent windows are counted apart rather than summed, since a subagent gets the tier injected the same as its parent (verified 2026-09-11, a spawned agent quoted all six of this repo's own rule files back) and folding the two would read one window's cost as two. A pure read with no watermark and no store, so a re-run is free. It is also the one scanner here that does not resolve HARNESS_TRANSCRIPT_DIR – transcript-root reads the home dir directly, so a fixture pointing that variable elsewhere has no effect on this one alone.

session-ledger.nu ​

The per-session roll-up – one record joining the transcript against every other stream: turns, wall time, tool use, module fires, guard bounces, hook spans, and workflow or task-agent spend, weighted with exactly the ratios scan-agents.nu uses so a session figure and a workflow figure are the same unit. It computes on demand and banks nothing, and its point is to be read rather than re-derived, so a debrief or a handoff that currently reasons its way to these numbers can ask for them instead.

scan-context.nu ​

What is actually in the window – splits a session's context into three sources that go stale differently. Standing is the CLAUDE.md chain and the memory index, rebuilt into every request from disk and never written to the transcript, so it is measured off the files as they are now and flagged as the only guess in the tool. Injected is the attachment records Claude Code wrote, exact. Read is what the agent pulled through the Read tool, exact for the same reason. Sidechain records are subagent turns, counted separately and never folded into the main total. dump <id> <source> prints the full text of one injected source when the summary is not enough.

scan-lookups.nu ​

Is the lookup layer used – the one number the read-front / read-section layer was built to justify and nothing was measuring, since the original A/B and ellipsis findings were one-off analyses that never refresh. It matches on the command string rather than a tool name, because both scripts shell through Bash and the path in front of the name varies by caller. rate is pulls over pulls-plus-reads, reported beside the raw counts rather than alone since plenty of files are genuinely wanted whole – a ratio to watch move, not a score to hit.

scan-tags.nu ​

Is the tag vocabulary still controlled – a controlled pool only stays controlled if something watches it, and the failure is silent by construction: nobody notices the twentieth near-synonym landing, only a --tags installer search missing half the files a year later. The one tracker whose subject is on disk rather than in a transcript, it reads the frontmatter itself by shelling read-front.nu, so the estate has one frontmatter parser rather than two that can disagree. Each file is checked against a per-file CAP of 5 tags and each tag against a use-count FLOOR of 3, below which it is a label rather than a bucket. pool reports used-but-not-in-pool and its inverse, pairs finds tags that almost always co-occur as merge candidates, snapshot banks the day's state, and drift diffs the last two. Injected context files (ROLE, STYLE, PROJECT, DESIGN) are excluded outright, and one turning up carrying tags anyway is reported as a violation.

The Session Probe ​

probe-session.nu ​

Does SessionEnd actually fire – a measurement probe rather than a tracker. Wired to both SessionStart and SessionEnd it logs one line per fire, so report answers the question with starts as the denominator and ends as the numerator. It records the cause too, SessionStart's source and SessionEnd's reason, because an end hook that fires on /clear but not on a window close is a different fact to build on. It is an observer, never blocks, bails when HARNESS_HOOKS_OFF is 1, and any other error falls through to a silent exit 0.

Currently not answering. Both global registrations route through a trace.nu wrap naming a path that moved when hook-trace/ relocated on 2026-08-13, so the hook has errored on every session since and harness-session.jsonl stops dead on that date. The wrap was never taken off. The fix is an unwrap; the tracker is also slated for retirement into trace.nu once the trace is seen covering both events, keeping the stream as the historical record when it goes.

The Hook Trace ​

hook-trace/audit-hooks.nu ​

The static half – what should fire, answered off the settings JSON alone with nothing running. It parses the settings files rather than grepping them, since a project's escaped inner quotes stop a naive pattern dead and read a fully wired project as having no hooks at all, and it reads every file that can register a hook in both scopes, settings.json and its settings.local.json twin. Five findings gate the exit code:

  • FIRED TWICE – one script registered for one event under more than one distinct command string.
  • SAME NAME, TWO PATHS – the same basename on one event at two different files, the shape the real 2026-07-09 bug took.
  • CWD-RELATIVE – a path that resolves against the session cwd rather than the project, so it dies the moment an agent changes directory. Named rather than fixed, harness doctor --fix owns that.
  • DEAD PATH – a registration pointing at a file that is not there.
  • DEAD WRAPPER – a wrapped registration whose shim has gone while the hook it names is fine.

A sixth row, DEDUPED BY CC, is informational and deliberately does not gate, since Claude Code runs an identical handler once however many settings files register it. That fifth finding closes a real gap: the checker resolves every wrap back to its original command before checking anything, which keeps the report readable mid-trace but meant a dead shim in front of a live hook read as clean.

hook-trace/trace.nu ​

The runtime half – what actually fired, by rewriting hook registrations to route through this script as a transparent pass-through shim: same stdin, stdout, stderr, exit code, and blocking behaviour, with every span logged to the hooks stream. On this event system the stderr half is load bearing – exit 2 is the blocking signal and Claude Code feeds the hook's stderr back to the model as the reason while ignoring stdout entirely – so the shim writes nothing of its own to either stream, ever. wrap and unwrap toggle the routing, status shows what is wrapped right now, and report cross-references what fired against what was registered.

Two details carry weight. The wrap id is a hash of the event plus the command, never a counter, because Claude Code dedups identical handlers and a per-registration id would break that dedup and manufacture the exact double fire the tracer exists to detect – and the event is in the hash because probe-session.nu is registered on two events with a byte-identical command. And a missing sidecar entry fails closed: since every wrap shares one sidecar, losing that file would otherwise disarm every gate at once with nothing to see. It exits 2 on the two events where a block is safe and visible, PreToolUse and PostToolUse, and passes through elsewhere, still logging either way – exit 2 on UserPromptSubmit erases the prompt, and on Stop or SubagentStop it prevents stopping and loops the session.

The Read Side ​

The manager surfaces exactly one telemetry number today, the picker badge, and it reads the same store the scanners write.

stores/telemetry-dir.ts ​

The store address – the TypeScript half of the three-step resolve, plus pointerPath, writePointer (which merges, forward-slashes the path so the Nushell side can read it, and creates the named dir), and moveStores, the one-time catch-up that carries the named files out of ~/.claude on the install that first stamps the pointer.

stores/usage.ts ​

The badge feed – reads harness-usage.jsonl back and re-groups the raw fires per session before bucketing. Per session rather than per fire is deliberate: a module injecting a few hundred tokens on every prompt costs far more than one injecting twelve thousand once, and a per-fire average says the opposite. The cache holds the raw fires rather than an average, because a per-session figure cannot be recovered from a pre-averaged one.

parts.ts, views/stats.ts, views/modules-view.tsx ​

The display surface – parts.ts holds the weightOf seam where a weight is resolved, and a measured reading only ever raises a hand weight and never lowers it, because the bucket means footprint plus active model spend while telemetry measures footprint only. views/stats.ts is the measured-usage section of harness stats, absent rather than zeroed on a box that never scanned, and views/modules-view.tsx draws the two usage rows on the module and part sheets, said the same way at both levels.

models/purge.ts ​

The one telemetry read that is a safety rather than a display – it counts harness-usage.jsonl rows tagged with a purged project's folder name and reports them rather than offering them for removal, because the store's project field is a folder basename and not a path, so it cannot tell two projects of that name apart.

The gap. scan-guards.nu, correction-rate.nu, and session-ledger.nu have no installer surface at all and harness stats does not know they exist. That is parked behind a pending decision, not an oversight to fix on your own.

Environment Overrides ​

Every one of these exists so a test or a fixture can point somewhere disposable. Leave them unset for real use.

variablewhat it movesdefault
HARNESS_TELEMETRY_DIRthe whole store dir, streams and watermarksthe stamped dir, else ~/.claude
HARNESS_STOREthe pointer file itself~/.claude/harness-store.nuon
HARNESS_TRANSCRIPT_DIRthe projects root the scanners walk – scan-rules.nu is the one exception, it resolves the home dir directly and does not read this var~/.claude/projects
HARNESS_LESSONS_DIRthe lesson store correction-rate.nu readsthe project's .claude/memory/lessons
HARNESS_CLAUDE_HOMEthe global settings scope audit-hooks.nu reads~/.claude
HARNESS_REWRITESthe rewrite registry trace.nu writes, a manager store~/.claude/harness-rewrites.nuon
HARNESS_HOOKS_OFFset to 1, the recursion guard scan-agents.nu notify and probe-session.nu bail onunset
HARNESS_NUDGE_SPINEthe spine nudge.nu emits its suppressions through, set on the nudge side rather than here~/.claude/telemetry/telemetry.nu

Connects to ​

  • context – the nudge part's nudge.nu writes the nudges stream, the only live emit this module reads that it does not produce, and scan-nudges.nu reads the fires of that same layer post-hoc off transcripts. The nudge table's telemetry-spend entry calls scan-agents.nu pending for its count. Beyond that, the passive injectors context ships (inject-project.nu, inject-compact-handoff.nu) are exactly what INJECTOR_SIGS has to name to attribute a fire, scan-clock.nu counts what the clock part's hook wrote, and the budget gate reads the same token-weights.nuon ratios scan-agents.nu weighs with, from one source at modules/shared/. scan-rules.nu reads the structured instructions attachment that context's own compile-context.nu produces when it injects the rules tier, the exact handle for what a .claude/rules/ file loaded that turn.
  • memory – correction-rate.nu reads the lesson store's source field directly, so it doubles as a health check on memory's own capture habit. scan-lessons.nu sync writes the other half of that signal back, surfaces and last_surfaced, which lessons.nu's drop candidates check alongside hits, so a lesson the recall hook actually shows is never offered for deletion on hit count alone. Both fields cross as optional, because telemetry never installs into a project and memory does. lessons.nu add writes the meta stream inline rather than through the spine for the same reason.
  • hooks – hook-trace/audit-hooks.nu and hook-trace/trace.nu read and rewrite the same settings.json registrations the hooks module writes, the static-against-runtime pair that answers what should fire against what did.
  • harness/scripts/read-front.nu and read-section.nu – the generic lookup scripts scan-lookups.nu measures the use of, matched by command string rather than declared as a dependency. scan-tags.nu shells read-front.nu outright as its frontmatter parser.
  • installer – telemetry is not a part the registry knows about. It installs global through harness local into ~/.claude/telemetry/, tracked in ~/.claude/harness-local.nuon, and that same install stamps the store pointer and moves the existing stores across. The read side is five files under installer/src/, and stores/telemetry-dir.ts has to keep agreeing with every tracker's own store-dir def.
  • harness/TRACKERS.md, harness/CONFIGS.md, and frameworks/TELEMETRY.md – the roll-ups and the doctrine this page draws from, one naming every tracker and how it is wired, one the authority on every store, one the rule that a tracker is post-hoc unless the fact is provably unrecoverable. Each is owed an update, not just a read, whenever a tracker or a store here changes shape.
  • The condensed, end-user version of this page is the module's own USAGE.md, at harness/modules/telemetry/USAGE.md.