360 Secure SkillHub
360 安全技能中心

claude-usage-companion

在常开 VPS 上用 Node 与 ccusage 读取本地 Claude 用量，统计月度累计消耗与月末预测，按 warn_pct/critical_pct 阈值告警，并可在设定的锚点时间提醒用户发起首个交互提示；通过 cron 定时运行，可用 timezone、plan、anchor、alert_command 等配置调整，仅报告与提醒，不自动化模型调用。

decisionvex
decisionvex
热度 23.21
最近更新 2026-06-18 16:01:43
分类：数据依赖：代码执行 / 读写文件应用场景：报告撰写 / 自动化脚本 / 日程安排 / 工作流

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add claude-usage-companion
Metadata
name
claude-usage-companion
description
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.

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.

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.