The Health-Score Plugin - Why I Built It
There’s a moment in every long Claude Code session where things go subtly wrong.
Claude starts referencing a function that doesn’t exist. It suggests an import from a package you never installed. It forgets context from 20 messages ago. The output looks confident but it’s wrong in quiet, hard-to-catch ways.
This is context degradation. And until I built Health Score, I had no reliable way to see it coming.
What Health Score Does
It adds a single number to your Claude Code status line: 0–100.
- 100 = fresh session, full coherence
- 50 = halfway through useful capacity
- < 40 = stop and compact before continuing
The formula isn’t linear. Claude doesn’t degrade linearly - it stays coherent until roughly 73% context fill, then drops fast. The score curve reflects that.
The Implementation
The score reads context_window.used_percentage from Claude Code’s native stdin data. No API calls, no hooks needed for the token count itself. Just math applied to a number that’s already there.
The stop hook is the critical piece. When score drops below 40, Claude is blocked from continuing until you /compact. This sounds annoying. In practice, it’s a relief - you stop second-guessing whether you should compact and just do it when prompted.
Why It Works
Constraints that save you from yourself are worth 10x the tools that let you do whatever you want.
Health Score is a forcing function. It makes the right behavior (compact early, compact often) the path of least resistance.