AGENTS.md

Guidance for coding agents working on Claude Usage VS Code Activation and Watcher in the claude-usage-cost project.

Project overview

This guide covers src/extension.ts activation and refresh behavior. The extension initializes pricing, creates UsageStore, restores cached state from VS Code global storage, registers commands, updates the status bar, and starts file watching plus polling for transcript changes.

Primary source files

• src/extension.ts owns activate, deactivate, initialLoad, runFull, runIncremental, startWatching, stopWatching, saveState, and updateStatus.
• package.json declares activationEvents, commands, and configuration.
• src/parser.ts provides serialize, restore, fullScan, and incremental.

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 activation lightweight by restoring cached state before cold scanning when possible.
• Guard full and incremental scans with the scanning flag to avoid overlapping scans.
• Debounce watcher events before incremental scan.
• Keep polling as a fallback when recursive file watching is unavailable.
• Stop watcher, poll timer, debounce timer, and state save timer on deactivate or restart.

Testing

Use mocked UsageStore and timers to cover cache restore, cold scan fallback, config changes, watcher restart, status metric off, and full refresh command. Verify no overlapping scan runs.

PR checklist

• Commands remain registered in package.json and extension activation.
• Auto refresh can be disabled.
• State restore invalidates when dir or dedupe mode changes.
• npm run check-types and npm run compile pass.