claude-usage-companion

Monitor your Claude programmatic credit pool and align your interactive window — on your always-on box. Since June 2026 Anthropic meters non-interactive usage (Claude Agent SDK, `claude -p`, Claude Code GitHub Actions, third-party agents) from a SEPARATE monthly credit pool ($20 Pro / $100 Max 5x / $200 Max 20x, API rates, no rollover) instead of your 5-hour interactive window. claude-usage-companion (1) tracks that credit pool — month-to-date burn, projected month-end spend, and an alert before you run dry so automations don't stop unexpectedly; and (2) reminds you, the human, at your anchor time to send your first interactive prompt so your 5-hour window lines up with your working day. Use this skill when the user mentions Claude usage limits, the programmatic/Agent-SDK credit pool, running out of credits, monitoring claude -p or GitHub Actions spend, ccusage, usage reports, budgeting Claude automation on a VPS, or wants to align/start their interactive session window. It only reports and reminds — it never automates the model or circumvents any limit.

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.

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.

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.

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)

Field	Meaning	Default
timezone	IANA tz for all clock math — set this	UTC
plan	pro / max5x / max20x → sets the credit cap ($20/$100/$200)	max5x
monthly_credit_usd	Override the cap if your number differs	null
warn_pct / critical_pct	Alert thresholds (% of cap, actual or projected)	80 / 95
anchor	Local time you start work (window reminder)	08:00
reminder_enabled	Send the anchor-time nudge	true
alert_command	Shell command to receive alerts on stdin (e.g. post to Slack). null = stdout + companion.log	null
ccusage_cmd	How 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.