claude-usage-companion#

Keep your Claude usage on an always-on box healthy after the June 2026 usage split — when programmatic usage ( claude -p, Agent SDK, GitHub Actions, third-party agents) moved onto a separate monthly credit pool instead of your interactive 5-hour window.

It does two clean, hands-off jobs:

1. Monitor the credit pool — month-to-date burn, projected month-end spend, and an alert when you're on track to exhaust it (the pool has no rollover; when it's gone, automated requests stop).
2. Remind you to align your interactive window — at your anchor time it nudges you (a human) to send your first prompt, so your 5-hour window tracks your working day.

Replaces claude-session-warmer. That skill primed the interactive window with claude -p, which no longer works: as of ~June 15 2026 claude -p draws from the separate credit pool and does not anchor the 5-hour interactive window. This companion is the honest successor — it never automates the model and never circumvents a limit; it only reports and reminds.

What it is NOT#

No automated priming of the window, no scripted interactive input, no token/credential tricks, no limit circumvention. Usage data is read locally with ccusage (a parse of ~/.claude — no model calls, no window side effects). Cost is USD at API rates, the same basis as the credit pool.

Prerequisite#

An always-on box (the VPS where you run OpenClaw / Claude Code) with Node 18+ and ccusage. Fast path: npm i -g ccusage.

Setup — 1, 2, 3#

Run on the box, from the skill folder.

1. Tell it your timezone, plan, and start time.

bash

cp config.example.json config.json
# edit: "timezone" (e.g. "Africa/Johannesburg"), "plan" (pro | max5x | max20x),
#       and "anchor" (the local time you start work, e.g. "08:00")

2. Check the box and see your burn.

bash

node bin/usage-companion.mjs check     # verifies node + ccusage + reads your usage
node bin/usage-companion.mjs report    # month-to-date burn, projection, top models

3. Schedule it.

bash

node bin/usage-companion.mjs install   # prints a ready-to-paste cron block
crontab -e                             # paste it, save

Now the box checks your credit pool a few times a day (alerting only when you cross a threshold) and reminds you at your anchor time to start your interactive session.

Commands#

• check — verify Node + ccusage are available and config is valid (run first).
• report — month-to-date spend, projected month-end, top models (no side effects).
• guard — evaluate thresholds; alert only if over warn_pct/ critical_pct (what cron runs).
• remind — emit the anchor-time "start your session" nudge (what cron runs).
• status — show config and next scheduled actions.
• install [--cron-only] — print the cron block ( --cron-only is pipeable to crontab -).

Configuration ( config.json)#

FieldMeaningDefaulttimezoneIANA tz for all clock math — set thisUTC``plan``pro / max5x / max20x → sets the credit cap ($20/$100/$200)max5x``monthly_credit_usdOverride the cap if your number differsnull``warn_pct / critical_pctAlert thresholds (% of cap, actual or projected)80 / 95``anchorLocal time you start work (window reminder)08:00``reminder_enabledSend the anchor-time nudgetrue``alert_commandShell command to receive alerts on stdin (e.g. post to Slack). null = stdout + companion.log``null``ccusage_cmdHow to invoke ccusage["npx","-y","ccusage@latest"]

For your exact remaining balance, the authoritative source is the "Usage credits" line in /usage inside Claude Code; report/ guard approximate the pool from local ccusage cost, which on an always-on automation box is essentially all programmatic.

Files#

• bin/usage-companion.mjs — the engine (Node; only external tool is ccusage).
• config.example.json — copy to config.json and edit.
• README.md — public overview.