@v1nvn/tokens weekly downloads statistics

@v1nvn/tokens

The home of the tokens plugin — and its plugin root: the tokens-report CLI and the mod's island share src/, the hooks module sits at hooks/register.tsx (.ts/.tsx the engine loads directly, no build), with engine tests at tests/ and the state contract at types/. One scan of the local session transcripts feeds both — per-model token usage and cache hit rate for the last 24 hours, plus daily totals for the last 7 days — and neither spends model tokens to tell you what the model cost.

User-facing docs: root README.

Quickstart

In Claude Code, the plugin is the way in — a mod draws two surfaces the model never reads: /tokens-usage opens the full report as a pane (refreshed on open and every 5 minutes while it shows; nothing draws and nothing execs until then), and /tokens-top draws the live session as a pane — context window and its eaters, token and thinking flow off the streaming chunks, rate-limit windows with resets, the agent roster and what runs now, all fed by engine pushes, no exec, no polling.

claude plugin marketplace add v1nvn/agentic
claude plugin install tokens@agentic

In a terminal, bare:

npx -y @v1nvn/tokens@0.55.1 usage

Usage

Invocation	Does
/tokens-usage	the full report, as a pane
/tokens-top	this session live — context + eaters, flow, limits, agents, as a pane
npx -y @v1nvn/tokens@0.55.1 usage	per-model table: input/output/cache-write/cache-read tokens, cache hit rate, 24 h window + 7-day daily totals

Works for every profile writing to ~/.claude/projects — default claude, claudez, headless claude -p runs alike. Files older than the 7-day window are skipped by mtime, keeping the scan under a second even with a large transcript history.

Semantics: input_tokens is the uncached input only; the modeled context is input + cacheRead + cacheWrite. Hit rate = cacheRead / (input + cacheRead + cacheWrite). One API response counts once: the transcript writes a response per content block and again when a session resumes, all under one message id — the largest-output snapshot is the response. Dispatched agents' transcripts (<session>/subagents/) count toward their own model's row. On the GLM Coding Plan, cached tokens count fully against quota, so a high hit rate saves latency, not quota.

Develop

yarn workspace @v1nvn/tokens test       # the CLI side (vitest)
claude plugin validate packages/tokens  # the mod, as the engine reads it
claude plugin test packages/tokens      # the mod, through the engine
yarn lint && yarn typecheck             # from the repo root (typecheck
                                        #   covers tsconfig.mods.json too)

The mod API is early access and moves between Claude Code releases — a build that refuses the module loads nothing, so validate after every engine update and re-vendor types/claude-code.d.ts (repo root) from the engine-laid .claude-plugin/types/ when it changes. Read references/mods.md first.

Modules

File	Role
src/index.ts	bin entry (tokens-report) — dispatch, exit codes
src/cli.ts	the CLI surface — usage + --json parsing, pure
src/aggregate.ts	the one usage math: JSONL line → per-model/per-day accumulation
src/scan.ts	the CLI's transcript walk (node-fs)
hooks/register.tsx	the mod: execs the CLI into the /tokens-usage pane; draws the /tokens-top pane from engine pushes
src/format.ts	the report both doors render
src/text.ts	line model + fixed-width primitives — tokens' internal home
src/top.ts	the /tokens-top pane layout — ink-tagged segments from engine pushes
src/index.ts	the CLI source the mod execs — node runs it directly, nothing built

Contracts

• Reads transcripts only; writes nothing.
• The island never reads transcripts ($.fs.read caps at 4 MiB); every number is one node <plugin root>/src/index.ts usage --json exec through the session's Bash tool — the same scan npx tokens-report runs. First /tokens-usage may ask to allow that command once; allow and it is remembered.
• The mod's surface (the pane) is drawn by the engine and never enters the model's context; the CLI prints the same report bare.