# Telemetry

> Show tool-usage stats from the local telemetry log — which tools a session burns context on, which days were busy, what failed. Use for "tool stats", "what did I spend context on", "which tools am I using most".

- Skill: `djnsty23/telemetry` (Agent Skill)
- Install (CLI): `npx skillmds@latest add djnsty23/telemetry`
- Raw SKILL.md: https://api.skillmd.com/api/skills/djnsty23/telemetry/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: djnsty23 (https://skillmd.com/u/djnsty23)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/djnsty23/telemetry

---


# Telemetry

A PostToolUse hook writes one line per tool call to
`.claude/reports/telemetry-YYYY-MM-DD.jsonl`. **Metadata only** — timestamp,
session, cwd, tool name, input and output *sizes*, and whether the call
succeeded. No tool input or output content is ever written, which is what makes
it safe to leave on in a repo that handles credentials; the hook's suite asserts
that by feeding a canary secret through and grepping the log for it.

## Reading it

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/telemetry-report.js"           # today
node "${CLAUDE_PLUGIN_ROOT}/scripts/telemetry-report.js" --days=7  # the week
node "${CLAUDE_PLUGIN_ROOT}/scripts/telemetry-report.js" --days=0  # everything
```

It prints the event count, distinct tools, per-day totals, and a per-tool table
of calls and kilobytes, biggest first.

## Interpreting it

The number that usually matters is **KB per tool**, not calls. Fifty `Bash` calls
returning a line each are cheap; three `Read`s of a lockfile are not. A session
that feels slow and shows most of its bytes in `Read` is usually one where a
targeted `Grep` would have done.

`failed` counts in the last column are a rough signal — the hook infers success
from the absence of an error marker, so treat a nonzero count as "look at what
happened", not as an exact figure.

A day missing from the table means no tool calls were recorded, which is not the
same as no work: if the hook is disabled or not installed, every day is missing.
Check that the current day appears before drawing conclusions from a gap.

## Turning it off

Set `CLAUDE_TELEMETRY_DISABLED=1` in the environment. The hook checks it first
and exits before writing anything.

Do **not** edit the plugin's `hooks.json` in the installed tree to disable it —
installed plugin files are replaced wholesale on the next marketplace update, so
the change would silently come back.

## Upstream export

Set `CLAUDE_OTEL_ENDPOINT` to also POST each event as OTLP JSON. It is
fire-and-forget with a 500ms timeout: an unreachable collector cannot slow or
fail a tool call, and the local file is written either way.

## Proving the run

**Observable:** the event count and the number of files it read, printed before
any interpretation.

The report prints its own population for this reason — "Read is your top tool" is
a different claim over 40 events than over 4,000, and an empty log and a missing
hook produce the same silence. If the count is zero, say the hook may not be
running rather than reporting a quiet session.