⏰ when-claude

Find the optimal time to trigger your Claude Code 5-hour window

Stop your quota from dying mid-peak. Make your resets land when you need them most.

🌐 English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Español · Français · Deutsch

---

Scanned 544 session files, 13,692 assistant turns (last 14 days).
Total token-weighted load: 1,602,031,406

Token-weighted distribution:

  08:00   112,607,641    7.0%  █████████████████
  09:00   149,627,350    9.3%  ███████████████████████
  10:00   194,492,420   12.1%  ██████████████████████████████
  11:00   140,385,822    8.8%  ██████████████████████
  ...
  15:00   170,453,459   10.6%  ██████████████████████████
  16:00   151,133,472    9.4%  ███████████████████████
  20:00   127,383,709    8.0%  ████████████████████

Gap detected: 01:00 - 05:00 (5h)
Recommended local anchor: 05:00
Window resets (local): 10:00, 15:00, 20:00, 01:00

--- For claude.ai scheduled tasks (stored in UTC) ---
UTC anchor: 21:00
Cron expression: 0 2,7,12,21 * * *

---

🕐 What's the Claude Code 5-hour window?

Every Claude Max plan runs on a 5-hour rolling usage window. Here's the idea in plain English:

1. Your first request starts a 5-hour timer. When you fire the first message of your day (or after any ≥5h idle gap), Claude opens a fresh "window" and begins counting.
2. Everything you send in those 5 hours shares one quota bucket. All messages, all agents, all tool calls — one shared budget.
3. After 5 hours the bucket resets. A brand-new window begins the moment you send your next request.

Why does this matter? Because the time of your first request decides where all your reset boundaries land for the rest of the day. Start at 8 AM → resets at 1 PM / 6 PM / 11 PM. Start at 5 AM → resets at 10 AM / 3 PM / 8 PM / 1 AM. Different start times give you completely different quota coverage.

The optimal trick: if your real crunch hours are 2–5 PM, you want a reset to land inside that peak — say 3:30 PM — so the peak gets split across two buckets, effectively doubling your available capacity during crunch time. Most people unknowingly let a single bucket drain straight through their peak and waste half the potential.

when-claude reads your actual Claude Code logs, figures out when you really work hardest, and recommends the precise trigger time that aligns your window boundaries with your peaks.

🛠 How it works

1. Reads ~/.claude/projects/**/*.jsonl — Claude Code's per-project session logs.
2. Weights every assistant turn by real billing cost: input + 1.25 × cache_create + 0.1 × cache_read + 5 × output, then multiplies by model pricing (opus 5× / sonnet 1× / haiku 0.25×).
3. Bins into 24 hourly buckets over the last N days (default 14).
4. Finds the quietest 5-hour gap via adaptive thresholding (2% → 5% → 10% → 15% → 25% of peak).
5. Simulates the 5-hour window chain from every candidate trigger time inside that gap, scoring by downstream reset utility minus a bleed penalty (prior activity keeping a window still open) minus an organic collision penalty (you'd already have triggered yourself).
6. Picks the best trigger time and converts it to a UTC cron for claude.ai scheduled tasks.

📦 Install

git clone https://github.com/Yellow4Submarine7/when-claude.git ~/src/when-claude
mkdir -p ~/.claude/skills
ln -s ~/src/when-claude ~/.claude/skills/when-claude

Then open Claude Code and ask:

"When should I trigger my Claude window?"

Claude invokes the skill automatically. Or run it standalone:

node ~/.claude/skills/when-claude/recommend.mjs

🚀 Usage

# Default: analyze last 14 days of your history
node recommend.mjs

# Exclude hours where you run unattended background agents
node recommend.mjs --ignore-hours 22-3

# Shorter window if your schedule recently changed
node recommend.mjs --days 7

# JSON output for post-processing
node recommend.mjs --json

⚙️ Applying the recommendation — two options

Option A — claude.ai Cloud scheduled tasks (recommended)

Runs on Anthropic's servers. Your laptop can be asleep. Zero local setup.

1. Open https://claude.ai/code/scheduled
2. Click New task
3. Paste the UTC cron from the tool output (it's already UTC — claude.ai stores every cron in UTC regardless of your local timezone)
4. For the task prompt, any minimal text works: ping or echo ready. Anthropic opens a session on their side, which opens the 5-hour window.

⚠️ Stagger note: claude.ai applies a ~3 minute stagger at execution time for load distribution. If your cron says 0 2,7,12,21, the actual fire happens around :03. If you need tighter alignment, move your cron 3 minutes earlier.

Option B — Local cron (for Linux boxes or always-on machines)

Needs your machine to be awake at each fire time. Great for Linux servers; less reliable on a laptop that sleeps.

# Edit crontab
crontab -e

# Add this line (example for local anchor 05:00)
0 5,10,15,20 * * * /usr/bin/env claude -p "ping" >/dev/null 2>&1

claude -p "prompt" runs Claude Code in non-interactive print mode — one short request just to "open the window", then exits.

⚠️ macOS laptop caveat: plain cron only fires if the Mac is awake. For reliable local scheduling on a sleeping Mac you'd need pmset wake schedules (requires sudo, fragile across updates). If you want to avoid that complexity, use Option A — that's exactly what claude.ai scheduled tasks are for.

🎛 Options

Flag	Purpose
--days N	History window in days (default 14). Use 7 if your routine just changed.
--ignore-hours SPEC	Exclude hours from analysis. Formats: 22, 21-23, 22-3 (wrap-around), 12-13,22-3 (multiple ranges).
--json	Machine-readable JSON output.
--help	Show usage.

❓ FAQ

Why not just use freshquota? freshquota is the ancestor of this project and deserves the credit. It analyzes call count (not token weight — less accurate for heavy users where one Opus session outweighs dozens of Haiku pings), and it triggers locally via launchd + pmset (requires sudo, macOS-only). when-claude uses token-weighted analysis and targets claude.ai Cloud scheduled tasks — no daemon, no sudo, works anywhere.

What if my distribution is flat? You'll see "No clear pattern detected." Use Claude Code more, shorten --days 7, or exclude noisy hours with --ignore-hours.

The anchor is 3 AM — my laptop is asleep! Use Option A. claude.ai Cloud scheduled tasks run on Anthropic's servers; your laptop can be fully asleep.

Can I force a specific anchor? Not through this tool — just type your desired cron into claude.ai directly. This tool is for finding the best anchor, not applying an arbitrary one.

🙏 Credits

Built on top of freshquota by @anniebuildz — the gap-detection and window-chain simulation are adapted from there. Token-weighted analysis, --ignore-hours, UTC cron output, and Skill packaging are new in this project.

📄 License

MIT

---

Built with ❤️ for Claude Code power users

Inspired by freshquota · MIT License