claude-warmup

English · 한국어 · Website

A tiny tool that keeps a Claude (Pro/Max) 5-hour usage window always running, so your first message never starts a full 5-hour wait for the Claude usage limit to reset. A background check runs every few minutes, and only when no session window is active does it send one very short message ("hi", on haiku) through the official claude CLI. It also shows your current session and weekly usage, with reset times.

$ claude-warmup
Claude Warmup v0.3.0

Usage  checked 08:42 · claude /usage
  Current session (5h)  █████░░░░░░░░░░░░░░░  23%  resets 11:00 (in 2h 17m)
  Weekly · all models   ████████░░░░░░░░░░░░  41%  resets Tue 10:00
  Weekly · Sonnet       █░░░░░░░░░░░░░░░░░░░   7%  resets Tue 10:00

Auto warm-up
  Status      ● on (launchd, checks every 5 min)
  Schedule    all day · every day
  Last ping   06:00 ✓ haiku-5-5 · window until 11:00
  Next ping   ~11:00, right after the current window resets

Why

Claude's session limit runs in 5-hour windows that start with the first message after the last window ended (help center). If nothing is running when you sit down, your own first message starts the full 5 hours. claude-warmup starts a new window the moment the last one ends, so a window is always already running: whenever you start, part of the 5 hours has passed and the next reset is closer.

No warm-up      09:00 ──────────── work ──────────── 14:00 reset
                (your first message at 9 starts the full 5 hours)

claude-warmup   06:00 ─ ping ─ 09:00 ─ work ─ 11:00 reset ─ work ─ 16:00 reset ─ 21:00 reset
                (windows run back to back: start at 9 → reset at 11; start at 13 → reset at 16)

• It does not raise your limits. You just stop starting from a full 5-hour wait. On average the next reset is about 2.5 hours away instead of 5.
• The weekly limit is separate and resets at a fixed time. One haiku "hi" barely touches it.

What makes it different

You can also warm up the window with a fixed-time cron job or a hosted CI runner. claude-warmup asks for less trust and less guessing:

	claude-warmup	Fixed-time cron or CI job
Where it runs	Your own computer or server	Often a hosted runner, with your Claude token copied into its secrets
Your credentials	Never read or copied; the official claude CLI keeps them	Token has to be exported and stored elsewhere
When it pings	Only when no window is open, checked every 5 minutes	At fixed times, even if a window is already running
Cost of a check	0 tokens (local /usage)	Each run is a real message
Usage view	Session, weekly and per-model usage with reset times	None

How it works

1. The OS scheduler (macOS launchd, Linux systemd or cron, Windows Task Scheduler) runs claude-warmup tick every N minutes (default 5).
2. If the last known window is still running, the tick does nothing and exits: no claude call.
3. Otherwise it reads usage with claude -p /usage. That is a local Claude Code command: it uses no quota (0 tokens, $0).
4. Only when no window is active does it send the warm-up: claude -p "hi" --model haiku --tools "" --system-prompt "…" --safe-mode --no-session-persistence It is a minimal request with tools, MCP servers, hooks and CLAUDE.md turned off, and no session is saved.
5. It records the new window's reset time from the reply's rate_limit_event and sleeps until then.

So "every 5 hours" follows the real end of each window, not a wall clock. If you start a window yourself by using Claude, it adapts.

Security

• claude-warmup never reads your Claude credentials. The official claude CLI does all the auth.
• API-key variables such as ANTHROPIC_API_KEY are removed from the child process, so pings always count against your subscription and never bill an API key.
• Zero-dependency Node.js, small enough to read in one sitting.

Requirements

• Node.js 18+
• The Claude Code CLI, logged in with a Pro/Max subscription:

curl -fsSL https://claude.ai/install.sh | bash

claude auth login

If you only use the Claude desktop app, claude-warmup can find the Claude Code copy bundled inside it, but a standalone install is sturdier across updates.

Install

npm install -g github:jungtaejoon/claude-warmup

claude-warmup install

Or run it straight away without a global install. install copies the app into its data folder and the service runs that copy, so it keeps working after the npx cache is cleared.

npx github:jungtaejoon/claude-warmup install

Usage

Command	What it does
claude-warmup / status	Usage and schedule (--json, --short, --cached)
claude-warmup install	Turn on auto warm-up
claude-warmup uninstall	Turn it off (--purge also deletes settings and logs)
claude-warmup ping	Send a warm-up now
claude-warmup config	Show settings; config <key> <value> changes one
claude-warmup logs	Recent activity (-n 50)
claude-warmup doctor	Check your setup

This is the beginning of the README. Read the rest at the original. Read the full README ↗