AGENTS.md

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

Project overview

This guide covers src/pricing.ts. The pricing engine maps model ids to built-in or user-provided rates, flags heuristic matches as estimates, and computes input, output, cache write, cache read, and total cost from token counts.

Primary source files

• src/pricing.ts owns PRICING_AS_OF, BUILTIN_PRICES, setPricingOverride, resolvePrice, and computeCost.
• src/types.ts defines ModelPrice, TokenCounts, and CostBreakdown.
• src/parser.ts calls resolvePrice and computeCost while aggregating buckets.
• package.json exposes claudeUsageCost.pricingOverride.

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

• Treat PRICING_AS_OF as the repository pricing snapshot date; do not describe it as current beyond that date.
• Keep overrides first in the index so user-provided matches win.
• Sort match patterns by descending length so specific model ids win over broad family patterns.
• Preserve exact versus estimated status so the dashboard can warn on heuristic pricing.
• Keep computeCost pure and unit-testable.

Testing

Test exact built-in model matches, override matches, longest-pattern priority, unknown opus, unknown sonnet, unknown haiku, completely unknown model, and category cost math.

PR checklist

• Rate changes update display names and match patterns together.
• Override shape remains compatible with package settings.
• Estimated models are surfaced as warnings.
• npm run check-types and npm run compile pass.