t1k:meter
| Field | Value |
|---|---|
| Module | t1k-orchestration |
| Version | 2.9.24 |
| Effort | low |
| Tools | — |
Keywords: claude-code-mod, cost, meter, mod, telemetry, tokens, usage
How to invoke
Section titled “How to invoke”/t1k:metert1k-meter — usage-metering mod
Section titled “t1k-meter — usage-metering mod”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.
Contract
Section titled “Contract”- Observer only. Never denies, rewrites, calls the network, or changes an event; every hook ends
return next(e)witheunchanged. 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 (novkey, one write per record) and the floor recorder does nothing. Nothing depends on this mod. Pin:mod-pin.json(minVersion2.1.287,testedVersion2.1.296); doctor check 89 compares it withclaude --versionand checks thathooks.jsonnames./register.tsand 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
hooksrow kind and the reader’shookWallsection are reserved and stay empty.
What it records
Section titled “What it records”JSONL, one object per line, to <outDir>/<sessionId>.jsonl. Default outDir: ~/.claude/telemetry/t1k-meter.
kind | From | Fields |
|---|---|---|
start | session.start | ts, sessionId, version, model, isInteractive |
turn | turn.complete | ts, 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) |
measure | session.measure, only when something changed | changed, 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.*).
Read it
Section titled “Read it”bun .claude/skills/t1k-meter/scripts/meter-report.cjs [--dir D] [--since YYYY-MM-DD] [--section S] # loops, agentTypes, models, coldResume, context, hopsbun .claude/skills/t1k-meter/scripts/floor-report.cjs [--dir D] [--baseline FILE] [--paths] # the floor, by category, vs a plain-Claude-Code baselineJSON 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.
Kill criteria
Section titled “Kill criteria”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.
Configure
Section titled “Configure”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.
Known limits
Section titled “Known limits”$.fs.writehas 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.readlimit 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-reportprints the sampled-sessionnbeside every rate and saystoo fewunder n = 5). The engine holds the NEXT turn’s start (andclaude -pexit) 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 inregister.tsdoes 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.jsonand.claude-plugin/types/into this folder when it loads the mod; they are gitignored in the kit source and never authored.
Executed by
Section titled “Executed by”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.
Check it
Section titled “Check it”claude plugin validate .claude/skills/t1k-meterclaude plugin test .claude/skills/t1k-meter # CI: node .claude/skills/t1k-meter/tests/mod-tests.test.cjs