Skip to content

t1k:meter

FieldValue
Modulet1k-orchestration
Version2.9.24
Effortlow
Tools—

Keywords: claude-code-mod, cost, meter, mod, telemetry, tokens, usage

/t1k:meter

A Claude Code mod (in-process function-hook plugin), not a prompt skill. Claude Code loads it by itself from ~/.claude/skills/t1k-meter/ (.claude-plugin/plugin.json + hooks/hooks.json, which names the one module ./register.ts: the meter, with the context-floor recorder inside its turn.complete handler); this file only makes the folder a valid T1K skill so the module pipeline ships it. Verified on the shipped shape (this SKILL.md with disable-model-invocation: true) by an isolated install on 2026-10-04: a real t1k init --global --kit core --modules t1k-extended --release modules-20261004-072647, then claude -p against a local mock, loaded it as t1k-meter@skills-dir and wrote JSONL rows with no prompt text. Background and how to add the next mod: docs/claude-code-mods.md.

  • Observer only. Never denies, rewrites, calls the network, or changes an event; every hook ends return next(e) with e unchanged. A failure inside the mod becomes one debug-log line (t1k-meter: record failed: ...) and the turn carries on.
  • Needs Claude Code >= 2.1.287; v2 needs >= 2.1.296. Below 2.1.287, or with hooks/mods disabled (--bare, --safe-mode, disableAllHooks, managed policy), the folder is inert and the classic hooks cover everything. From 2.1.287 to 2.1.295 the meter behaves exactly as v1 (no v key, one write per record) and the floor recorder does nothing. Nothing depends on this mod. Pin: mod-pin.json (minVersion 2.1.287, testedVersion 2.1.296); doctor check 89 compares it with claude --version and checks that hooks.json names ./register.ts and that the file and its relative imports exist.
  • No hook-wall timing. Wrapping the classic hooks to time them failed its own kill criterion (K1), so v2 ships without those wrappers; the hooks row kind and the reader’s hookWall section are reserved and stay empty.

JSONL, one object per line, to <outDir>/<sessionId>.jsonl. Default outDir: ~/.claude/telemetry/t1k-meter.

kindFromFields
startsession.startts, sessionId, version, model, isInteractive
turnturn.completets, sessionId, turnId, agentId, loop (main / subagent / other = Workflow agent or engine fork / unknown), reason, durationMs, model, the four token counts (null when the turn had no usage, never 0); v2 adds v: 2, agentType (registered agent type; null for the main loop, except a routed hop’s main loop, which carries env MR_DELEGATE_AGENT when MR_SPAWNED=1 and the value matches ^[A-Za-z0-9._:-]{1,64}$) and parentSession (env MR_PARENT_SESSION_ID, a label, null when unset)
measuresession.measure, only when something changedchanged, contextTokens, contextWindow, contextPercent, costUsd (session-cumulative), rateLimits

v2 rows buffer in memory per file and are written once per turn.complete; past 128 KiB the file continues as <sessionId>.2.jsonl, .3.jsonl. Rows written by v1 have no v key and stay valid; the readers accept both and nothing is backfilled.

Floor document: once per SAMPLED session id (1 session in floorSampleEvery, default 10, chosen from the session id; the other sessions record nothing, never a summary document; main loop only, in the turn.complete of the first completed turn that has a context figure), <floorDir>/<sessionId>.json, default ~/.claude/telemetry/t1k-floor: model, version, detail: 'full', sampling: {every: N}, the callMs (wall) of the one $.session.usage({ breakdown: 'full' }) call, window/total/floor tokens, categories, the top 40 memory files (~ for $HOME), agent, skill and per-server MCP token totals. floorTokens is every used category except Messages (System prompt, System tools, MCP server instructions, Memory files, Skills, …); deferred rows, Free space and the compaction buffer are not in it. The full call counts with the token-count API (CPU and wall cost: PR #4361); there is no turn.step hook, so no per-chunk cost. Documents written before this change have detail: 'summary': local estimates with System tools about 4.4K tokens too high (floorTokens +27..30%); floor-report still reads them, flags them estimate:true and never averages them with full ones. Floor figures quoted before this change (83,933 tokens one-off, ratio 1.591) are summary estimates.

Privacy: no prompt text, answer text, tool input/output, command, path (except memory-file paths), file content, env value (except the MR_PARENT_SESSION_ID label and, in a routed hop, the pattern-checked MR_DELEGATE_AGENT name) or refusal explanation is ever read or written. Local files only, no network, zero model tokens (no additionalContext, no session.append, no $.model.*).

Terminal window
bun .claude/skills/t1k-meter/scripts/meter-report.cjs [--dir D] [--since YYYY-MM-DD] [--section S] # loops, agentTypes, models, coldResume, context, hops
bun .claude/skills/t1k-meter/scripts/floor-report.cjs [--dir D] [--baseline FILE] [--paths] # the floor, by category, vs a plain-Claude-Code baseline

JSON on stdout (t1k-meter-report/1, t1k-floor-report/1); every rate carries its n, and lowSample:true under 30. Exit 3 means no usable data (unknown, never zeros). Weighted units are not dollars.

K2: p95 flush over 50 ms at 500 rows or one write per turn is more. K3: p95 callMs over 100 ms (summary) or 1500 ms (full) across 30 or more sessions. K4: one token added to any prompt or request. Any breach removes that piece.

The outDir and floorDir userConfig options (plugin.json). Set them through settings, keyed by plugin name:

{ "pluginConfigs": { "t1k-meter": { "options": { "outDir": "/some/dir" } } } }

A leading ~/ is expanded by the mod itself ($.fs does not): HOME, then USERPROFILE; if neither is set the record is dropped and the debug log says so.

  • $.fs.write has no append, so a segment is rewritten whole: per record below 2.1.296, once per turn from 2.1.296 (segments of 128 KiB keep every read under the engine’s 4 MiB $.fs.read limit and bound the bytes rewritten per turn).
  • A floor document is written once per session id and never overwritten; a session that ends before its first completed main-loop turn, or that is not in the 1-in-10 sample, has none (floor-report prints the sampled-session n beside every rate and says too few under n = 5). The engine holds the NEXT turn’s start (and claude -p exit) for the full count (about 0.7-1.3 s wall on the real API), once per sampled session, i.e. in one session in ten; on a slow token-count endpoint that is about 2 x its slowest request, and the 8 s bound in register.ts does not shorten it (it only decides whether a document is written).
  • Cost is session-cumulative only; price a loop from its token counts and the model list price.
  • The engine writes tsconfig.json and .claude-plugin/types/ into this folder when it loads the mod; they are gitignored in the kit source and never authored.

The two reader scripts are run by a person or any agent on request; no model is needed to produce the numbers. meter-report.cjs and floor-report.cjs are deterministic, offline and read-only, so a cheap-tier agent can run them and relay the JSON. Reading the report and deciding what to optimise stays with a reasoning tier. The mod itself (hooks/*.ts) is run by Claude Code, never by an agent.

Terminal window
claude plugin validate .claude/skills/t1k-meter
claude plugin test .claude/skills/t1k-meter # CI: node .claude/skills/t1k-meter/tests/mod-tests.test.cjs