AlexandrAI AGENTS.md
agents-md

Claude Usage Deduplication Agent Guide

Agent guide for billable-message deduplication by Anthropic message id.

AGENTS.md

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

Project overview

This guide covers the dedupe behavior inside UsageStore.ingest. The extension can count each billable assistant message once by Anthropic message id, while still reporting raw token volume and duplicate entries removed.

Primary source files

  • src/parser.ts owns seen records, duplicatesRemoved, rawTokens, and the upgrade path for larger duplicate snapshots.
  • src/extension.ts wires the claudeUsageCost.dedupe setting and dashboard toggle.
  • media/dashboard.js exposes the dedupe toggle and duplicate summary card.
  • package.json declares the dedupe configuration setting.

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

  • Zero-token stream stubs must not claim a message id.
  • rawTokens should count every copy before dedupe so users can compare raw transcript volume with billed totals.
  • If a later duplicate has more tokens than the stored copy, remove the smaller bucket contribution and apply the larger one.
  • If dedupe is off, count raw entries and make the dashboard state explicit.
  • Keep totalMessages as billable messages after dedupe, not raw line count.

Testing

Create fixtures with the same message id in multiple files, a zero-token stub before a complete record, and a later larger copy. Verify duplicatesRemoved, rawTokens, totalMessages, bucket totals, and aggregate totals.

Failure modes

  • Claiming a zero-token id can drop the real billed record.
  • Keeping the first duplicate unconditionally can undercount when stream snapshots grow.
  • Deduping without removing the old bucket can double-count upgraded records.

PR checklist

  • Dedupe on and off both produce clear dashboard results.
  • Duplicate upgrades preserve one billed contribution.
  • Selftest can run with DEDUPE disabled for comparison.
  • npm run check-types and npm run compile pass.