CCLINE

A statusline runs on every single prompt render, which makes it the one piece of tooling most able to damage a session it has no business touching, and the usual failure is not a crash but silence. It also has to be right about numbers that are easy to get wrong: the obvious way to count tokens in a Claude Code transcript is to sum the usage on every line, which inflates the total 1.978x because one assistant message is written as several lines carrying the same cumulative figures, and the obvious way to report a total includes cache reads, which on one measured session outnumbered real input and output 429 to 1. Both mistakes produce a number that is stable, grows monotonically and is roughly the right order of magnitude, so nothing about it looks broken. A tool that fails soft has a third problem on top: a segment that is merely too slow renders empty and looks exactly like a healthy one.

ccline is a zero-dependency TypeScript toolkit covering all four Claude Code extension surfaces: the statusline, four hooks, four slash commands and three output styles. Every enabled segment races one shared 300ms deadline concurrently, a failing segment drops itself rather than the line, and the process exits 0 with an empty stderr whatever happens. Token totals are deduplicated by message.id against a rolling window of the last 2000 ids held in an incremental checkpoint, cache reads are excluded by default and restorable by config, and the budget is enforced by a test that renders a cold 1000-message transcript and asserts both that it finishes in time and that real values are still in the output. Because the render path is contractually silent, ccline doctor is the loud counterpart, with 9 check families and a self-test that proves all 25 of its checks can fail. Installation is npx ccline-cli install; the package is MIT and ships no runtime dependencies at all.

ccline is a statusline for Claude Code, plus the hooks, slash commands and output styles that sit alongside it. It reads one JSON object on stdin per prompt render and prints one line: context remaining, tokens, model, branch, cost, duration. I built it on two rules that end up deciding almost everything else. The first is that the render path never fails loudly. ccline statusline never exits non-zero and never writes to stderr, because a broken statusline must not be allowed to touch your session. Fail-soft is per segment, not per line, so a segment that throws, rejects, returns nothing, or is configured under a name that does not exist drops only itself and leaves the rest of the line intact.

The second rule is that slow is the same as broken. A line that misses its deadline renders empty and looks perfectly healthy while telling you nothing. I know that failure mode because I watched it on an earlier project: a segment asked for a 1520ms read behind a 1200ms abort, lost the race every single time for months, and nobody noticed, because fail-soft made a dead feature look identical to a healthy one. So the budget is asserted, not hoped for. Every enabled segment races one shared 300ms deadline concurrently, and a test renders a cold 1000-message transcript and asserts the whole line finishes inside it. That same test asserts the output still contains 1.2M tok and 18m, because otherwise the timing assertion would pass on a line that rendered nothing. Measured headroom is 5.0ms at 1000 messages and 11.8ms at 5000.

Most of the work turned out to be measurement rather than rendering. Claude Code writes one assistant message as several JSONL lines that all carry the same message.id and the same cumulative usage, so they are restatements, not increments. Summing every line instead of deduplicating by id inflates the total 1.978x: on a real transcript that is 1,056,805,602 naive against 534,220,602 true, over 1108 distinct messages. Cache reads are excluded from the headline figure for the same kind of reason. On one real session they were 348,167,965 against 811,270 of actual input and output, 429 to 1, and a number dominated 429 to 1 by cache traffic is not a number about your work. Both mistakes are invisible unless you go looking, because the wrong number is stable, grows monotonically and is roughly the right order of magnitude.

The pet segment is the one piece of decoration in the tool, and the size is the feature. The reference pet is a cat named bubba, squeezed into one terminal cell using the U+2596 quadrant block characters, so the entire canvas is a 2x2 bitmap and the medium holds exactly sixteen distinguishable pictures. He has five states: appear, alert, tailflick, sleep and idle. He has no whiskers and no eyes, because a quadrant only lights when at least half of it is inked, and a feature smaller than an eighth of the sprite cannot survive that trip. The first rasteriser lit a quadrant on any ink at all, and since every pose has ears, all five poses came out as the same solid block. The frame is a pure function of session state, with no timers and no randomness, because the statusline does not tick, it re-renders when Claude Code decides to, and a pet that jitters next to real numbers makes the real numbers look untrustworthy too. He is off by default, with a test asserting he stays off by default, and he adds zero new filesystem reads: he rides the memoised transcript read that tokens and duration already paid for. A pet that takes eight columns is a pet somebody turns off in a week.

Because the render path is contractually silent, it needs a loud counterpart, so ccline doctor names every symptom the renderer swallows: a settings file in a higher scope silently shadowing the one you just wrote, a stale invocation, a missing transcript, a segment rendering nothing and why. doctor --self-test feeds fabricated broken worlds through the real check functions and currently reports 25 of 25 checks proving they can fail, and a coverage guard fails the build if a new check family ships without a scenario that breaks it. The toolkit is 69 TypeScript files and 13,317 lines with no dependencies key in package.json at all, covered by 1035 tests across 55 files, run on five CI legs.

Four surfaces, one package, zero runtime dependencies. The statusline registers eight segments (context, tokens, model, branch, cost, duration, update, pet), seven of which are on by default. renderLine runs every enabled segment concurrently against one shared deadline and never rejects. The concurrency is not a flourish: if segments ran in sequence the budget would have to be divided by the segment count, so adding a segment would silently shrink every other segment's allowance. The deadline timer is deliberately not unref'd, and the unref it used to carry is a bug I shipped and then documented in place. An unref'd timer does not keep the event loop alive, so when the only pending work was a quiet segment with no outstanding I/O, node exited before the deadline fired, renderLine never settled, and the whole line vanished instead of one segment: the exact failure the module exists to prevent, wearing the costume of the mechanism meant to prevent it.

Reading the transcript is the expensive part, so it happens once per render and everything else rides that one read. The parser is incremental. A checkpoint in the cache file records the byte offset, the running totals, and a rolling window of the last 2000 message ids so deduplication survives across reads without the cache growing without bound. The checkpoint also fingerprints which file it belongs to using the first 512 bytes, because a size check alone catches only a replacement smaller than the offset, and a session file replaced by a longer one would resume into the middle of a stranger and keep reporting dead totals forever. On the 208MB transcript I measured against, the first cold render cannot finish inside 300ms, so tokens and duration drop once, a shorter line renders on time, the read completes after the line is written, the checkpoint lands, and every later render is complete at about 48ms. Degrading once beat blocking the prompt for a second at the start of every session.

The small details carry most of the correctness. The branch segment reads .git/HEAD directly rather than taking the transcript's gitBranch field, which reports the branch as of the last assistant message and therefore lies after a git switch until the next turn. Colour is gated on NO_COLOR alone and never on process.stdout.isTTY, because Claude Code captures the statusline's stdout so it is never a TTY: an isTTY check would disable colour permanently for every user while looking entirely reasonable in review. Every rendered part passes through one sanitiser at the boundary that strips C0, DEL and C1 control characters, since before it existed a segment could hide the user's scrollback, erase it, rewrite the window title, split the statusline into two lines, or beep on every render. Bidi overrides and zero-width characters are deliberately left alone, because they are text, not commands.

The art is generated, not checked in. A script holds bubba's five poses as 8x8 silhouette grids and emits the frames module, and its --check flag compares the committed file byte for byte against the generator, so a hand edit is a build failure rather than a silent fork. The same rule covers the images: every screenshot in the README is produced by running the real renderer over pinned fixtures, with a fixed clock so duration cannot tick, an in-memory transcript, a null cwd so branch cannot pick up the generator's own repo, and a literal environment so a developer's NO_COLOR cannot produce a colourless screenshot of a colourful tool. The update notifier is the only code in ccline that opens a socket, and it never runs from the render path: the check runs only from nine named commands a person types, fetches about forty bytes of dist-tags rather than the full packument, and writes the result into the existing cache file that the update segment then reads and nothing else.