AGENTS.md

Guidance for coding agents working on Codex Token Activation State Cache in the codexTokencount project.

Project overview

This guide covers activation and runtime orchestration in src/extension.ts. The extension initializes pricing overrides, creates UsageStore, restores cached parser state, registers commands, starts watcher and poll refresh, updates the status bar, and saves state on throttled intervals.

Primary source files

• src/extension.ts owns activate, deactivate, initialLoad, runFull, runIncremental, startWatching, stopWatching, saveState, updateStatus, and pushData.
• src/parser.ts provides serialize, restore, fullScan, and incremental.
• package.json declares activation events, commands, and configuration settings.

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

• Restore cached state before cold scanning when possible.
• Keep the scanning flag to prevent overlapping scans.
• Debounce file watcher events before incremental scans.
• Keep polling as fallback for platforms without recursive watch support.
• Save parser state synchronously on deactivate and throttle routine saves.

Testing

Use mocked timers and store methods for restore success, restore failure, refresh command, sessions directory change, status metric off, watcher restart, and polling fallback.

PR checklist

• All timers and watchers are disposed.
• Status bar metric selection remains consistent with package settings.
• npm test, npm run compile, and npm run check-types pass.