AGENTS.md

Guidance for coding agents working on Codex Token Parser in the codexTokencount project.

Project overview

This guide covers src/parser.ts. UsageStore scans Codex session JSONL files, maintains per-file offsets and leftovers, tracks current model, project path, and session id, and ingests token_count events into hourly buckets.

Primary source files

• src/parser.ts owns UsageStore, fullScan, incremental, scanFileFrom, ingest, parseUsage, parseTotalUsage, and aggregate.
• src/types.ts defines TokenCounts, Bucket, DashboardData, and project and model rows.
• src/parser.test.ts verifies parser behavior with synthetic logs.
• src/selftest.ts runs the parser outside VS Code for independent checks.

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

• Keep parser code free of VS Code imports so tests and selftest remain plain Node runnable.
• Preserve chunked reading and leftover buffering for large and partially written JSONL files.
• Parse only relevant records by checking for token_count, model, cwd, id, or rate limit markers before JSON.parse.
• Keep model, cwd, and session id as per-file rolling context for incremental scans.
• Treat malformed records and unreadable files as skips, not fatal errors.

Testing

Cover turn_context model changes, event_msg token_count records, top-level session metadata, appended records, truncated files, malformed lines, and no-session directories.

PR checklist

• Incremental scan produces the same aggregate as a full scan for appended files.
• Parser state serializes and restores across extension activation.
• npm test, npm run compile, and npm run check-types pass.