A mod for Claude Code
Know how close you are to the line.
Plimsoll draws a heads-up display in the band above the Claude Code prompt: the context window, your rate limits, what the tokens would have cost, and the repository you are in. A ship's Plimsoll line shows how deep it may safely sit; this one shows how close a session is to its limits.
- No account
- No server
- No telemetry
- MIT licensed
── ◢ PLIMSOLL · *waves* ──────────────────────────────────── 1: USAGE 2: STATS 3: GIT ──
CTX ▰▰▰▱▱▱▱▱▱▱▱▱ 28% 276.7K used · 723.3K left TODAY 43.6M tok ~$8.86
/\_/\ 5H ▰▰▰▰▰▱▱▱▱▱▱▱ 43% resets 3h 17m WEEK 89.0M tok ~$31.40
( ^.^ )/ WEEK ▰▰▰▰▰▰▰▱▱▱▱▱ 56% resets 1d 2h MONTH 427.3M tok ~$142.10
(")(") ~- Runs in
- Claude Code, above the prompt
- Reads
- Transcripts already on disk
- Needs
- Node.js; git; gh optional
- Version
- 0.3.0, MIT
What it shows
Three tabs and a kitten.
Switch with /hud usage, /hud stats and /hud git, or focus the band with ctrl+x tab and press 1, 2 or 3. Gauges are green below 50%, yellow from 50%, orange from 75% and red from 90%.
Usage
How full the context window is, in tokens used and left. Your 5-hour and weekly rate-limit windows, with the time to each reset. Tokens and estimated cost for today, this week and this month.
Stats
Your peak hour and busiest weekday, the last 30 days and the last 12 months as sparklines, and your most active day, week and month.
Git
Repository, branch, ahead and behind, staged, modified, untracked, conflict and stash counts, and the last commit. With gh signed in, the branch's pull request, its review state and check counts, and the latest CI run.
The kitten
A small ASCII kitten beside the gauges. It idles, types while Claude works, sleeps once five minutes pass without a turn, and panics when a gauge reaches 90%.
How the numbers are produced
Measured where it can be, summed where it cannot.
Nothing on the band is a guess. Each figure is either reported by Claude Code or added up from files already on your machine, and the one estimate is marked as one.
Context and rate limits
Measured by Claude Code itself and handed to the plugin. Plimsoll does not estimate them.
Tokens and statistics
Summed from the transcripts under your Claude config folder, in local time, weeks from Monday, when a session starts and after every turn. A cache means later scans read only the files that changed.
Estimated cost
Each response's tokens, cache writes and reads included, priced at Anthropic API list prices as of 2026-10-06. An estimate, never a bill.
Git and CI
git status, stash and log for the folder you are in; gh for the pull request and the latest run. gh is the only part that touches the network, and only GitHub.
The limits
What it will not do.
Everything here is in the README too. Nothing is left out because it is inconvenient.
- Dollars are an estimate at API list prices, shown with a ~. They are not a bill: a subscription is not charged per token.
- A model missing from the price table counts as $0 until the table is updated.
- Rate-limit windows are only reported on a subscription.
- A transcript that was forked or copied is counted twice for the rows it shares.
- A mod cannot draw over the transcript or register its own key chord, so the HUD takes rows of its own and uses Claude Code's band shortcuts.
- The band needs about 110 columns for its two columns side by side; narrower, they stack, and below 48 columns it is not drawn.
- The mod API is early access and may change between Claude Code releases.
Install
Two lines in a Claude Code session.
Pick a scope when asked: user scope loads it in every session. Node.js must be on your PATH, git is needed for the git tab, and a signed-in gh adds pull requests and CI.
/plugin marketplace add akshit-bansal11/plimsoll
/plugin install plimsoll@plimsollComing from usage-board? Uninstall usage-board@usage-board and remove the usage-board marketplace first. The scan cache carries over; the hidden state does not.
Free and MIT licensed. There is no account to make, no server to reach and nothing reported back: the plugin is the repository, and the marketplace installs it from there.