AGENTS.md

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

Project overview

This guide covers src/parser.ts. UsageStore recursively scans Claude Code JSONL transcript files, reads appended bytes in chunks, skips lines without usage payloads before parsing JSON, and converts message usage objects into hourly buckets.

Primary source files

• src/parser.ts owns UsageStore, listFiles, fullScan, incremental, scanFileFrom, ingest, and aggregate.
• src/types.ts defines TokenCounts, Bucket, AggregateRow, DashboardData, and related payload types.
• src/selftest.ts runs the same parser outside VS Code for independent checks.
• src/extension.ts creates the store and triggers full or incremental scans.

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 parser code independent of VS Code imports so selftest and plain Node validation keep working.
• Keep transcript directory handling in the extension layer; parser should receive a directory and scan JSONL files under it.
• Preserve chunked reads and leftover buffering so large files and partial final lines are handled safely.
• Keep the cheap usage substring check before JSON.parse to avoid parsing unrelated large transcript lines.
• Treat malformed JSON, missing usage, and unreadable files as non-fatal skips.

Testing

Use synthetic JSONL fixtures for complete lines, partial lines, malformed lines, no-usage lines, nested message usage, top-level usage, and appended bytes. Use selftest only against a placeholder transcript directory, never against private data in published artifacts.

PR checklist

• Parser still runs without vscode imports.
• Large transcript files are read incrementally.
• Invalid records are skipped without crashing.
• npm run check-types and npm run compile pass.