Claude Code statusline: what ccclub puts there

Claude Code lets you replace the bar under the prompt with the output of any command: it hands your script a JSON payload on stdin and prints whatever comes back. That is a genuinely open slot, and most people fill it with context percentage and a git branch. ccclub fills it with the two numbers that are otherwise a command away — how much of your rate-limit windows you have spent, and where you sit on your group's board today. This page is about that one line: what it contains, how it stays current, and what it deliberately refuses to do.

What the line shows

Up to three segments, separated by dim pipes, and every one of them optional:

 Fable 5 xhigh | 5h: 15% / 7d: 43% / Fable: 8% | #11/67 $19.0

• Model and effort. The display name Claude Code passes in, with a parenthetical context size shortened so "(200K context)" does not eat the line, followed by the session's reasoning effort level when the current model has one. The effort word is coloured by intensity, so a session left on the highest setting is visible without reading it.
• Limits. The percentage of your five-hour window and your seven-day window consumed, plus a third figure when a model-scoped weekly limit applies — labelled with whatever family name the API returns. Each percentage turns amber at 60% and above, and red at 80% and above, which is the only warning the line gives.
• Rank and cost. Your position on your first group's board for today and today's estimated cost, with the top three positions in gold, silver and bronze. The segment is wrapped in a terminal hyperlink, so in a terminal that supports them the rank is click-through to the group dashboard, and in one that does not it renders as ordinary text.

Segments degrade independently. No group yet, an expired credential, a model with no effort knob — whatever is missing is simply absent, and the rest of the line still prints. If nothing at all is available, the statusline prints nothing rather than an error.

Turning it on and off

ccclub statusline on writes a statusLine entry into ~/.claude/settings.json pointing at ccclub-statusline, a small binary npm installs beside the main ccclub command. It is a separate executable on purpose: the main CLI pulls in an argument parser and a colour library that the render path has no use for, and this one runs on every turn. Because Claude Code has to be able to find that binary by name, the command requires ccclub to be installed globally and says so plainly instead of writing a setting that would silently do nothing.

ccclub statusline off removes the entry and records the decision. That record matters: ccclub will enable the statusline once, on its own, on a machine where nothing else is configured — and the opt-out marker is what stops that automatic path from ever bringing it back. Running ccclub statusline with no argument prints the current state and the command it would install.

Where the numbers come from

Not from the payload Claude Code hands it. The renderer reads exactly two things out of that JSON — the model display name and the effort level — and takes everything else off disk. Limit percentages and rank live in small cache files under ~/.ccclub/, written by ccclub sync: the sync asks Anthropic's usage endpoint for your own percentages, using the credential Claude Code already holds locally, and asks the ccclub API for your rank. The render path opens those files, formats a line and exits.

Sync runs often enough for that to work without anyone thinking about it. ccclub init installs Claude Code hooks that fire when a turn stops and when a session ends, and on macOS a LaunchAgent that syncs every five minutes on top of them. On Linux and Windows there is no such agent: the hooks are the whole of the schedule, so the cache is as fresh as your last turn. Either way, while you are actually using Claude Code it is rarely more than a few minutes old.

What a slept-through night does to it

Both triggers stop while the machine is asleep — a hook needs a turn to end, and the periodic agent is suppressed outright. Measured on one laptop, that meant effective gaps of about forty minutes in ordinary use and eight hours across a night, and the old result was a limits segment that vanished for hours the next morning with nothing to explain why.

Two changes fixed it, both visible in the line. A reading older than three hours still renders, dimmed and with a trailing tilde: plainly not live, still better than a gap. Past twelve hours it is dropped, because by then the window it describes has emptied and refilled and the figure would be false rather than merely old. And the statusline now kicks off a background sync when it sees the cache has aged — after the line is already on stdout, never before, and no more than once every five minutes however those syncs turn out. A machine that slept heals itself within a turn or two of waking.

What it never does

The render path makes no network request. None: it reads stdin and three small JSON files, and every one of those reads is wrapped so that a missing or corrupt file drops one segment instead of failing. Both the payload and the caches are treated as untrusted input, since the line is printed raw into a terminal between escape codes — text from either is stripped to printable ASCII and length-bounded before it is used, and the dashboard URL behind the rank hyperlink has to match a strict pattern or the link is dropped and the text printed plain.

It also does not alert, predict, or notify. There is no burn-rate projection and no "you will run out at 4pm" — just a percentage that changes colour. If you want prediction, run a monitor built for it; this is a readout, and it is honest about being one.

If you already have a statusline

Claude Code has one statusLine slot, so two tools cannot both own it. ccclub resolves that in the only direction that cannot lose someone's work: if the configured command is not exactly ccclub-statusline, ccclub treats it as yours and refuses to touch it. ccclub statusline on declines with a message telling you to remove the existing one first; the automatic enable never fires at all; and uninstalling only ever removes a command that is byte-for-byte ours. Even a pipeline that mentions ccclub by name — piping our output into your own filter, say — counts as yours under that rule, which is the conservative reading and the right one.

If you would rather build your own, Claude Code's own payload already carries rate_limits.five_hour and rate_limits.seven_day for subscription accounts, with a percentage and a reset timestamp each, and its status line documentation (read 2026-09-19) has worked examples. ccclub's version exists because it also knows your rank, and because the limit figures it shows are fetched independently rather than waiting on the first API response of a session.

Last updated 2026-09-29. Corrections welcome on GitHub.