AGENTS.md

Guidance for coding agents working on Claude Usage Aggregate Payload in the claude-usage-cost project.

Project overview

This guide covers UsageStore.aggregate in src/parser.ts. Aggregation converts hourly buckets into per-model rows, totals, daily series, monthly cap gauge data, reconstructed sessions, and warning strings for the webview.

Primary source files

• src/parser.ts owns aggregate, computeCapGauge, computeSessions, addInto, and finalizeRow.
• src/types.ts defines DashboardData and every nested payload shape.
• media/dashboard.js renders cards, split bars, charts, sessions, model table, and warnings from the payload.
• src/extension.ts calls store.aggregate for status bar and webview pushes.

Setup commands

npm install 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 <transcript-dir>

Change rules

• Keep aggregate side-effect free except for reading current store state.
• Filter buckets by cutoff before adding them to rows and totals.
• Sort rows by descending total cost so expensive models surface first.
• Keep totals display as All models and preserve totalTokens as a finalized derived field.
• Warnings should describe unpriced and estimated models without blocking dashboard rendering.

Testing

Use buckets across several models, days, and hours. Verify cutoff filtering, row sorting, total aggregation, daily series ordering, warning generation, cap gauge values, and session grouping.

PR checklist

• DashboardData shape stays compatible with media/dashboard.js.
• Unpriced models do not crash cost computation.
• Totals equal the sum of visible rows for the selected window.
• npm run check-types and npm run compile pass.