claude-session-warmer

Make your Claude Pro/Max usage window start when you want it to — not whenever your

first prompt of the day happens to land.

What it does (and explicitly does not do)

Claude meters usage in a rolling 5-hour window anchored to your first message. Start

at 09:40 and your window is 09:40–14:40; your afternoon reset is pinned there. Send one

trivial primer at 05:00 instead and the window opens 05:00–10:00 — a fresh window is

already waiting when you sit down, and every reset that day lines up with your working

hours.

claude-session-warmer sends that primer through the official claude CLI, on a

schedule, on your always-on box — the same VPS where you already run OpenClaw and an

authenticated Claude Code. (A laptop is the wrong host: it's asleep when you're not

working, so it can't fire the early primer. The whole point is a machine that's always

on.)

It does not bypass or beat any limit. You cannot exceed the 5-hour cap or the weekly

cap, and this skill does not try to — it only changes when the window opens. That

distinction is what keeps it inside Anthropic's terms; read references/tos.md before

publishing or sharing.

Prerequisite (you almost certainly already have this)

The box must have the official Claude Code CLI installed and logged in to your

Pro/Max subscription — exactly the setup you already use to develop with OpenClaw on that

VPS. If claude -p "hi" answers on that box, you're ready. Do not copy auth tokens

from another machine — log in on the box itself via the official flow (that token-copying

is the one thing Anthropic enforces against; see references/tos.md).

Setup — 1, 2, 3

Run these on the VPS, from the skill's folder.

1. Tell it your timezone and start time.

cp config.example.json config.json
# edit config.json: set "timezone" (e.g. "Africa/Johannesburg"), your "anchor"
# start time (e.g. "05:00"), then set "enabled": true

2. Check the box can warm the window, and preview the plan.

node bin/session-warmer.mjs check      # confirms claude is installed + logged in here
node bin/session-warmer.mjs schedule   # shows the primer times (e.g. 05:00 10:05 15:10 20:15)

If check fails, it tells you exactly what to fix (install the CLI, or run claude once

to log in).

3. Schedule it.

node bin/session-warmer.mjs install    # prints a ready-to-paste cron block
crontab -e                             # paste the block; save

Done — the VPS now warms your Claude window every day so your windows align to your hours.

(Prefer OpenClaw/Cowork scheduled tasks? install also prints that recipe — one task per

primer time running node bin/session-warmer.mjs warm.)

Hard constraints (do not violate)

1. Official CLI only. The primer is sent via the real claude -p binary. Never

extract or reuse OAuth tokens, never spoof the Claude Code client, never route the

primer through the Agent SDK with subscription auth or any third-party harness.

1. The user's own subscription, logged in on the box itself. No token copying between

machines, no shared accounts.

1. One trivial prompt per primer. The point is to open the window, not do work.
2. Opt-in. enabled ships false. Do not arm it without the user setting it true.
3. Honest framing. Describe it as window alignment, never as "bypassing limits."

How the math works

schedule walks from anchor to day_end in steps of window_minutes + buffer_minutes.

Each step lands just after a window closes, so the primer at that time starts a brand-new

5-hour window. With the defaults (anchor 05:00, window 300m, buffer 5m): 05:00, 10:05,

15:10, 20:15. All clock math is timezone-aware via Intl — set your IANA timezone and

DST/travel are handled; no extra dependencies.

Commands

• check — verify the CLI is installed + authenticated on this box (run this first).
• schedule — print today's primer times (no side effects).
• warm — fire one primer now (respects enabled + dry_run); this is what cron runs.
• install [--cron-only] — print cron / scheduled-task lines (--cron-only is pipeable).
• status — show config + the next primer time.

Files

• bin/session-warmer.mjs — the engine (Node, no deps).
• config.example.json — copy to config.json and edit.
• references/tos.md — why the official-CLI path is permitted and what is not. Read before publishing.
• README.md — user-facing overview for the public repo.