Scaffold mismatch is a quota bug, not a syntax bug

It is when Claude Code generates code based on the framework conventions in its training data, and the actual project uses different conventions for the same framework. The most common flavor right now is Next.js 16 + React 19, which ship breaking changes to routing, server components, caching semantics, and the public import surface compared to what the training snapshot knew. Claude writes something that would have compiled a year ago, the build fails, you paste the error back, Claude tries again. Every step of that loop is billable against your plan. The ClaudeMeter marketing site (the one you are reading) literally has a five-line AGENTS.md at /Users/matthewdi/claude-meter-website/AGENTS.md that says 'This is NOT the Next.js you know' as the first-line defense against this exact behavior.

Both tools read ~/.claude/projects/<repo>/*.jsonl and sum what the client wrote. That counts tokens, but it misses three things that make scaffold-mismatch retries expensive: the 4.7 tokenizer expansion (applied server-side, after the JSONL is frozen), the hidden adaptive-thinking tokens Claude Code omits from the display, and the inability to group multi-turn retries under a single 'feature attempt.' The cost of a scaffold mismatch is the sum of every retry's hidden reasoning plus the retokenized input, and that sum only exists as one float on Anthropic's server: usage.seven_day_opus.utilization. ClaudeMeter reads it.

It lands on seven_day_opus, the Opus-only weekly window. That field lives at /Users/matthewdi/claude-meter/src/models.rs line 23, declared as Option<Window>. The Window struct above it (line 4 to 7) has a utilization: f64 and a resets_at: Option<DateTime<Utc>>. The extension POSTs that struct to http://127.0.0.1:63762/snapshots on every 60-second tick (extension/background.js line 2 sets BRIDGE, line 3 sets POLL_MINUTES = 1). Every time a scaffold mismatch triggers a retry, the float on line 23 goes up.

It is a guard file the author added after watching Claude Code spend Opus quota regenerating Next.js 15 era code against a Next.js 16.2.4 codebase. It sits at the repo root and contains nothing but: 'This is NOT the Next.js you know. This version has breaking changes: APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.' Claude Code picks it up automatically and changes its behavior from 'generate confidently' to 'read the docs first.' It is a free, local fix. What it does NOT fix is the quota damage from the sessions before you wrote it; that is on seven_day_opus forever until the weekly window resets.

There is no universal number because the cost is content-dependent, but you can measure your own. With ClaudeMeter installed, run 'curl -s http://127.0.0.1:63762/snapshots | jq .[0].usage.seven_day_opus.utilization' before and after a failing generate-build-fix-build loop, and the delta between those two floats is the weekly percentage you spent on that one mismatch. In practice, the retries are disproportionately expensive compared to the successful first-shot version of the same task, because: (1) the error feedback you paste back is input tokens, retokenized; (2) 4.7 tends to think harder when it sees build errors, generating more hidden reasoning; (3) each retry repeats context that had already been billed once.

Anything that shipped breaking changes after the training cutoff. In this repo the two that bite are Next.js 16 (the async API migration, turbopack build semantics, and the new file-based routing for parallel routes) and React 19 (the new use() hook, the removed forwardRef requirement, the deprecated useContext signature). The same pattern applies to Tailwind 4 (dropping tailwind.config.js for a CSS-first @theme directive), Remix 3, and anything in the TanStack ecosystem that rewrote its public API between versions. The package.json of this website shows the exact versions at risk: next 16.2.4, react 19.2.4, tailwindcss ^4.

No, and it is not supposed to. It bends Claude's behavior toward reading docs before writing code, which catches the obvious cases (wrong import path, wrong file location, wrong API signature). It does not catch subtle semantic mismatches: a function that exists with the same name but different behavior between Next.js 15 and 16, or a Tailwind utility class that was renamed silently. Those you only discover at build or runtime, after the tokens are spent. The honest stance is: AGENTS.md reduces the retry count, ClaudeMeter tells you what the remaining retries cost.

Yes. The extension fetches /api/organizations/{org}/usage every minute. Open the ClaudeMeter menu-bar popup and keep it visible while you're running a retry-heavy session; the '7d Opus' row updates live as the server-side float climbs. For scripted tracking, run a bash loop: 'while true; do curl -s http://127.0.0.1:63762/snapshots | jq -c &quot;[now, .[0].usage.seven_day_opus.utilization]&quot;; sleep 60; done'. That gives you a time-series of the quota drain; every inflection point lines up with a retry.

It hits every LLM coding agent whose training data is frozen before the frameworks it is writing for. The reason Claude Code feels especially painful on this is the combination of (1) plan-based quota rather than per-request billing, so cost is invisible until you hit 429, and (2) adaptive thinking on 4.7, which generates substantial hidden output on exactly the kind of 'why did this fail' reasoning a scaffold mismatch triggers. Cursor running on Claude hits the same quota. The quota read in ClaudeMeter is account-wide; it does not care which client spent the tokens.

It moves the cost to a different float. Sonnet retries bill against seven_day_sonnet and the shared five_hour window, both visible in the same /usage payload (seven_day_sonnet lives at models.rs line 22, five_hour at line 20). seven_day_opus is left untouched. So if your week's Opus bucket is already 80 percent spent and you hit a scaffold mismatch, switching the retry loop to Sonnet is the right move. You still pay quota, just in a bucket that is less likely to 429 you on your next planning step. ClaudeMeter surfaces all four floats side by side so you can pick the cheaper bucket to burn.