cc-cream

C.R.E.A.M. — Cache Rules Everything Around Me.

A lightweight status-line tool for Claude Code that turns the JSON Claude Code pipes to its status line into a glanceable, colored ≤3-row bar. The model never sees the output — it costs zero tokens.

What it shows

ctx:3% [30k] | cache:55% | ~$0.10
5h:22% ↺ 0m | 7d:36% ↺ Sat 21:00
Opus 4.7 (1M context) | example session

Rendered from a live Claude Code subscriber session (fixtures/subscriber.golden.json). A proper screenshot or asciinema recording will appear here after public release.

• Row 1 — this session: context-window occupancy, cache hit rate, session cost
• Row 2 — rate-limit budget windows: 5h and 7d usage + reset countdown (subscribers only; API users get one row)
• Row 3 — identity: model name and optional session name

The bar helps you avoid rate limits, keep the cache warm, and catch context fill before the model degrades — with cache economics as the organizing story.

Trust and data posture

• No network calls. The engine is a pure stdin → stdout transformer. It never opens a socket, fetches a URL, or calls home.
• No telemetry. Nothing is collected, reported, or logged anywhere.
• No runtime dependencies. Node built-ins only. npm install is for dev tools (Cucumber, Biome) — nothing that runs at render time.
• Zero tokens. Claude Code reads the bar output to display it; the model never receives it.

The only I/O is reading the JSON blob Claude Code pipes on stdin and writing one session-state file to ~/.claude/cc-cream-state.json (keyed by session ID, contains cost and rate-limit samples used for the burn projection).

Requirements

• Node.js — already present; Claude Code is a Node app.
• Claude Code ≥ 2.1.132 (released 2026-05-06). The cache figure requires context_window.current_usage, which landed in that release.
• The effort and thinking segments additionally require Claude Code ≥ 2.1.145; they stay hidden below that version.

Platform support

v1 supports macOS and Linux. Windows support is a planned fast-follow; the engine is pure Node and the only blocker is the statusLine shell-command wiring.

Install

Option 1 — Claude Code plugin (community catalog / self-hosted marketplace)

If cc-cream is listed in the community catalog:

/plugin install cc-cream

To use the self-hosted marketplace directly:

/plugin marketplace add bart-turczynski/cc-cream
/plugin install cc-cream

That's usually all you need: on the first session after install, cc-cream auto-wires its statusLine into ~/.claude/settings.json (you may need to restart or trust the workspace for the bar to appear). It only does this when no status line is configured — it never overwrites one you set for something else, and it never re-adds the bar after you remove it.

If you already have a status line and want to replace it with cc-cream's, run:

/cc-cream:setup

The /cc-cream:setup command runs the consent installer, which writes the statusLine block to ~/.claude/settings.json. Updates are automatic: when /plugin update drops a new version into the cache, the next render picks it up without any further action.

Option 2 — npm

npm install -g cc-cream

Then wire it into Claude Code with the bundled CLI:

cc-cream-setup

cc-cream-setup runs the consent installer (src/install.js). Without a global install you can run it through npx:

npx -y -p cc-cream cc-cream-setup

Option 3 — Manual GitHub clone

Download and install by cloning the repository, then run the consent installer:

git clone https://github.com/bart-turczynski/cc-cream.git
node cc-cream/src/install.js

The installer:

• Detects an existing statusLine and asks before replacing it
• Preserves any padding you have set
• Is idempotent — re-running when cc-cream is already installed changes nothing
• States the trust and restart requirement

After install, Claude Code must be trusted for the directory (if prompted), and you may need to restart it for the bar to appear.

Pick one install method. If you wire cc-cream via npm/manual (Options 2–3) and then install the plugin, the plugin won't take over the existing wiring — it points at your home copy, so /plugin update won't auto-update the bar. To switch to the auto-updating plugin, run /cc-cream:setup (or cc-cream-setup --uninstall first). Nothing breaks either way; it just stays on whichever method wired it.

Uninstall

Plugin users — two steps, in this order (Claude Code can't clean settings.json when a plugin is removed, so the wiring is cleared separately from the cache):

/cc-cream:uninstall          # 1. removes the statusLine wiring (run this FIRST)
/plugin uninstall cc-cream   # 2. drops the plugin

/cc-cream:uninstall also auto-cleans cc-cream's regenerable scratch (the copied runtime and session-state file); add --purge (/cc-cream:uninstall --purge) to also delete your ~/.claude/cc-cream.json config. The bar disappears on your next message — restart an already-open session to drop it immediately.

Order matters — but you're covered if you get it wrong. /cc-cream:uninstall lives inside the plugin, so once you run /plugin uninstall it's gone. Neither host command clears the statusLine block or the version cache. The renderer notices when it's running from a cache the host no longer lists as installed and self-suppresses, so the bar stops on the next session even though the inert statusLine line still lingers in settings.json.

To clear that leftover line once the plugin is gone, the guaranteed route is the copy of the uninstaller still in the cache — npm-free and always present. VERSION is the single directory under that path (run the ls first to read it off); /cc-cream:uninstall also prints the fully-resolved command:

ls ~/.claude/plugins/cache/cc-cream/cc-cream/        # e.g. 0.3.1
node ~/.claude/plugins/cache/cc-cream/cc-cream/VERSION/src/install.js --uninstall
# add --purge to also remove your config

The npm bin does the same job, but not always: a freshly published version is blocked by npm's min-package-age safe-chain guard (it reports "command not found") until it ages in, so use it only if the cache route isn't handy:

npx -y -p cc-cream cc-cream-setup --uninstall

You can always remove the statusLine key from ~/.claude/settings.json by hand.

npm / manual users:

cc-cream-setup --uninstall                 # npm (add --purge to also remove the config)
node cc-cream/src/install.js --uninstall   # manual clone

Uninstall removes the statusLine block only if it is cc-cream's — a statusLine you wired for something else is left untouched. It always cleans the regenerable scratch (the copied runtime and session state, both recreated on a reinstall); --purge additionally removes your ~/.claude/cc-cream.json config. The bar clears on your next message (restart an already-open session to drop it now).

Likewise, cc-cream-setup run non-interactively will overwrite an existing cc-cream statusLine but never a foreign one — pass --force to replace regardless.

Not sure what's left behind? cc-cream-setup --status prints a read-only footprint report — the statusLine wiring, every cached plugin version (the host never garbage-collects these), the marketplace clone + registration, the auto-wire marker, session state, config, and the manual runtime copy — so you can confirm a clean slate or see exactly what to remove.

Configuration

Every display decision is read from ~/.claude/cc-cream.json. Edit it by hand or ask Claude to. It is strict JSON with no comments. Every field falls back to its built-in default if missing or malformed — a typo degrades one value rather than breaking the bar; a whole-file parse error falls back to all defaults.

Because unknown or out-of-range fields are silently ignored, run the doctor after editing by hand to catch typos:

cc-cream-setup --check-config   # reports unknown keys / out-of-domain values; exits non-zero if any

{
  "numbers": "compact",
  "ttl": "auto",
  "percentage": "consumed",
  "segments": {
    "ctx":          { "on": true,  "row": 1, "order": 2, "amber": 30, "orange": 40, "red": 50, "basis": "window", "ceiling": 200000, "display": "basis" },
    "cache":        { "on": true,  "row": 1, "order": 3 },
    "write":        { "on": false, "row": 1, "order": 3.5 },
    "ttl":          { "on": true,  "row": 1, "order": 4, "amber": 50, "red": 80 },
    "cost":         { "on": true,  "row": 1, "order": 5 },
    "effort":       { "on": false, "row": 1, "order": 6 },
    "thinking":     { "on": false, "row": 1, "order": 7 },
    "api_ratio":    { "on": false, "row": 1, "order": 8 },
    "5h":           { "on": true,  "row": 2, "order": 1, "amber": 75, "red": 90 },
    "burn":         { "on": true,  "row": 2, "order": 1.5 },
    "7d":           { "on": true,  "row": 2, "order": 2, "amber": 75, "red": 90 },
    "peak":         { "on": true,  "row": 2, "order": 3, "start": 5, "end": 11 },
    "model":        { "on": true,  "row": 3, "order": 0.5 },
    "session_name": { "on": false, "row": 3, "order": 1 }
  }
}

Global keys

• numbers: compact (e.g. 38k) or exact (38000) for token magnitudes.
• ttl: cache time-to-live used to color the ttl segment — auto (recommended), 60, or 5 minutes. auto infers from rate-limit data when available.
• percentage: consumed (default) counts up — ctx:19% means 19% of the window is used, 5h:67% means 67% of the 5h budget is gone. remaining flips the budget/occupancy segments to count down (ctx:81%, 5h:33%). Only ctx, 5h and 7d flip; cache% (a hit-rate, not a budget) and ttl (a countdown) are unaffected. Thresholds are always expressed in consumed terms regardless of this setting.

Per-segment keys

Every segment accepts:

• on (boolean) — whether to show the segment
• row (1, 2, or 3) — which row to place it on
• order (any number) — lower = further left within the row

Colored segments additionally accept threshold keys. Thresholds mark the lower bound where that color begins.

Segment catalog

Any segment hides cleanly when its source field is absent — API users have no rate_limits; current_usage is null right after /compact; etc.

Row 2 is hidden entirely for API users (no rate_limits in stdin). Row 3 suppresses itself when all its segments are hidden.

Row 1 layout

Row 1 has two zones separated by |:

[ctx · cache · write · ttl · effort · thinking · api_ratio] | [cost]

Segments within zone 1 are also separated by |. Segments moved off their default row via config must land in a zone to appear on row 1.

ctx-specific keys

• basis: window (default) colors based on used_percentage of the real context window. ceiling colors based on total_input_tokens / ceiling, so the warning fires at the same absolute token count on any window size. On a 1M-context model the window basis stays green well past where quality degrades — set ceiling if you want an early warning that doesn't scale with the window.
• ceiling: token count the ceiling basis measures against. Default 200000.
• display: with basis: "ceiling", basis (default) shows the % toward the ceiling so number and color agree; window pins it to CC's window figure but still colors by the ceiling. No effect under basis: "window".

ctx thresholds

Default: amber: 30, orange: 40, red: 50 (percent consumed).

ttl thresholds

Default: amber: 50, red: 80 (percent of the resolved TTL consumed).

5h / 7d thresholds

Default: amber: 75, red: 90 (absolute used_percentage).

peak-specific keys

• start / end: hours in Pacific time (0–23, exclusive end) bounding Anthropic's faster-drain window. Defaults 5–11. Weekday-only (Mon–Fri) and the America/Los_Angeles timezone are hardcoded policy facts, not config.

Troubleshooting

cc-cream is built to degrade silently — if a stdin field is missing or malformed it just hides that segment rather than crashing. When the bar is unexpectedly empty or shorter than you expect, turn on diagnostics:

export CC_CREAM_DEBUG=1   # then trigger a render in Claude Code

Each render appends a line to ~/.claude/cc-cream-debug.log (override the path with CC_CREAM_DEBUG_LOG) listing which segments rendered, which were dropped, the resolved TTL window, and the stdin size. It never writes to the status line itself, so it costs zero tokens. Unset the variable to turn it off.

Development

See CONTRIBUTING.md for how to run the tests. The runtime uses only Node built-ins — no runtime dependencies.

License

MIT — see LICENSE.