Skip to content

Add cmd-mod-toks to the registry - #1153

Open
ArcticPole04 wants to merge 1 commit into
CommandCodeAI:mainfrom
ArcticPole04:add-cmd-mod-toks
Open

ArcticPole04 wants to merge 1 commit into
CommandCodeAI:mainfrom
ArcticPole04:add-cmd-mod-toks

Conversation

@ArcticPole04

Copy link
Copy Markdown

Add cmd-mod-toks

A tokens-per-second meter for Command Code. It reports the live generation rate beside the
working spinner and the exact rate in the footer once a request finishes.

The crowded part of this category is the estimate. Most meters divide a character count by 4,
which reads Chinese roughly 4x too slow and short chunks roughly 4x too fast. Three things
differ here:

  • Sampling uses message_update, not deltas. The event carries the whole partial message,
    so the count is invariant to how a provider fragments the stream, a mid-stream retry
    self-corrects as a shrinking total instead of counting withdrawn text twice, and tool-call
    arguments are counted — they are billed output tokens that never arrive as a text_delta.
  • Script-aware estimation. CJK counts as one token per character, other scripts as 1/3.6.
  • Calibration against the provider. Each request ends with the provider's own
    outputTokens; both billing styles are offered as candidates (providers that fold reasoning
    tokens into that figure and providers that do not) and the closer match wins.

When it cannot be right it shows nothing rather than a plausible wrong number: a decode span
too short to trust, a rate that implies buffered delivery, and silence longer than two seconds
all suppress the reading instead of printing a guess.

Entry

{
  "name": "cmd-mod-toks",
  "source": "cmd-mod-toks",
  "description": "Honest tokens-per-second meter: samples absolute message_update counts so retries and stream fragmentation cannot skew it, counts CJK as one token, and calibrates against the provider's own outputTokens.",
  "author": { "name": "ArcticPole04", "github": "ArcticPole04" },
  "repo": "https://github.com/ArcticPole04/cmd-mod-toks",
  "npm": "cmd-mod-toks",
  "kinds": ["command", "flag", "renderer"],
  "tags": ["metrics", "throughput", "status-line", "tokens"],
  "addedAt": "2026-11-17"
}

kinds reflects what the mod actually registers: addCommand (/toks), addFlag (three:
status, spinner, lang), and ui.override('spinner'). It registers no cmd.hooks, so
hook is deliberately absent.

source matches npm, consistent with every other npm-backed entry in the file.

What a reviewer will find

  • No network, no filesystem, no process access. cmd mods inspect reports
    reaches: none and imports: none — the mod reads host events and writes to cmd.state.
  • Read-only surfaces. Every mutation is a display toggle or a language switch; nothing
    touches the transcript, permissions, or model routing.
  • State is validated on read. cmd.state outlives the process that wrote it, so a stored
    value is checked before use rather than trusted.
  • Attribution is explicit. NOTICE.md records that two earlier MIT-licensed mods informed
    the measurement guards (cmd-footer for the plausibility ceiling and its 400 tok/s
    threshold, commandcode-tokenspeed-mod for the 600 ms EMA constant), with their copyright
    notices reproduced. It also states what is original here.
  • Authorship is disclosed. The README says the implementation was produced with an AI
    coding agent under human direction, and what that means for the license.

Testing

npm test runs 90 tests on Node's built-in runner; npm run typecheck passes. The suite is
written against defects observed while building the mod — retry double-counting, a single-frame
reasoning burst, CJK under-reporting, one-character deltas, missing usage, providers that
exclude reasoning tokens, late first tokens, interruptions, and sparse streams. The measurement
guards are also mutation-tested: invert one and the suite fails.

Pre-submission checks

  • registry.schema.json validated: name pattern, 203/240 description, author.name
    present, kinds all in the enum, tags all ^[a-z0-9-]+$, additionalProperties: false
    satisfied (no extra fields), no official/featured.
  • Exactly one entry appended, one mod per PR.
  • No trailing commas.
  • Package published at https://www.npmjs.com/package/cmd-mod-toks.

A tokens-per-second meter that reports the live generation rate beside the
working spinner and the exact rate in the footer once a request finishes.

The estimate is where most meters in this category go wrong: dividing a
character count by 4 reads CJK about 4x too slow. This one samples the
absolute count from `message_update` instead of deltas, so retries and stream
fragmentation cannot skew it, and it counts tool-call arguments that never
arrive as a text delta. Every request is reconciled against the provider's own
outputTokens, handling both billing styles for reasoning tokens.

kinds reflects what the mod registers: addCommand (/toks), addFlag (status,
spinner, lang), and ui.override('spinner'). It registers no cmd.hooks, so
"hook" is deliberately absent.

cmd mods inspect reports reaches: none and imports: none — the mod reads host
events and writes to cmd.state, with no network, filesystem, or process access.
NOTICE.md credits the two MIT-licensed mods whose measurement constants informed
this one and records what is original here.

90 tests pass on Node's built-in runner; typecheck is clean.

Co-authored-by: CommandCodeBot <noreply@commandcode.ai>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant