AGENTS.md

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

Project overview

This guide covers project attribution in src/parser.ts and the project table in media/dashboard.js. The parser tracks cwd from session metadata and turn context records, stores buckets by model, project path, and hour, and aggregates project rows with nested model breakdowns.

Primary source files

• src/parser.ts owns extractCwd, projectName, currentCwds, bucket project fields, byProject, and byProjectModel aggregation.
• src/types.ts defines ProjectRow and ProjectModelRow.
• media/dashboard.js renders simple and detailed project modes.
• src/parser.test.ts covers project preservation across incremental token_count events.

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

• Use project path for stable grouping and basename only for display.
• Preserve current cwd per file during incremental scanning.
• Do not publish private project paths in generated reports or docs; describe behavior with placeholders.
• Sort projects by total tokens first, then cost.
• Keep nested model rows sorted the same way inside each project.

Testing

Cover multiple projects in one session, appended token counts after a cwd change, multiple models within a project, unknown cwd, and project table rendering with escaped project names.

PR checklist

• Project grouping is stable across full and incremental scans.
• Dashboard title attributes escape project path text.
• npm test, npm run compile, and npm run check-types pass.