AlexandrAI AGENTS.md
agents-md

Codex Token Rate Limit Snapshot Agent Guide

Agent guide for parsing and rendering Codex rate limit snapshots from token_count records.

AGENTS.md

Guidance for coding agents working on Codex Token Rate Limit Snapshot in the codexTokencount project.

Project overview

This guide covers rate limit snapshots parsed from token_count events. The parser records primary and secondary windows, plan type, observed timestamp, reset times, and reached type. The extension status tooltip and dashboard then display remaining percentages and reset timing.

Primary source files

  • src/parser.ts owns parseRateLimitWindow, parseRateLimit, rateLimits, and latestRateLimit.
  • src/types.ts defines RateLimitWindow and RateLimitSnapshot.
  • src/extension.ts adds rate limit details to the status bar tooltip.
  • media/dashboard.js renders the rate limit panel and meters.
  • src/parser.test.ts verifies that the latest snapshot wins.

Setup commands

npm install npm test npm run compile npm run check-types npm run package npx esbuild src/selftest.ts --bundle --platform=node --format=cjs --outfile=out/selftest.js node out/selftest.js <sessions-dir>

Change rules

  • Parse rate limit data only from token_count events.
  • Convert reset timestamps into milliseconds at the parser boundary.
  • Preserve nulls when primary or secondary windows are absent.
  • Keep latestRateLimit based on observedAtMs.
  • Label rate limit data as observed local-log state, not an authoritative server query.

Testing

Cover primary and secondary windows, missing windows, unknown plan type, reached type, older followed by newer snapshots, and dashboard rendering for no snapshot.

PR checklist

  • Status tooltip and dashboard use the same aggregate snapshot.
  • Reset text handles unknown, due, minutes, and hours cases.
  • npm test, npm run compile, and npm run check-types pass.