Fresh — execute a prompt at the next 5h usage reset

Overview

Detect the next 5-hour usage-window reset and fire a prompt at it, so a long run gets a full fresh quota window. Two modes:

• Default (same session): one-shot CronCreate injects the prompt into the current session. Context is preserved.
• --clear (fresh session): Windows Task Scheduler launches a brand-new headless claude -p session at reset. Fresh context window + fresh quota. Survives closing this session. Resumable afterwards.

Usage

/fresh <prompt text | path/to/prompt.md> [--clear] [--at HH:MM] [--now]

If the argument is an existing file, the prompt becomes: Execute the instructions in <absolute path>. If it looks like a path but doesn't exist, stop and ask — don't schedule against a missing file or silently treat it as literal text.

Step 1 — Find the reset time

node "$HOME/.claude/skills/fresh/resolve-reset.cjs"   # Windows: node "%USERPROFILE%\.claude\skills\fresh\resolve-reset.cjs"

Prints one JSON line: {reset_utc, reset_local, source, utilization_pct}. Use reset_local directly — the resolver already converted from UTC. The source field tells you how much to trust it:

Why this changed: the old skill used ccusage's endTime as the reset. Because ccusage floors the window start to the hour, that value fires early — landing the prompt in the old, exhausted window. The 5h line under the REPL is accurate because it reads five_hour.resets_at; the resolver reads the same source (via the status line's cache, falling back to the live endpoint).

• --at HH:MM given → skip the resolver, use that (local time).
• source: ccusage-heuristic-EARLY → don't trust the bare value. Ask the user to read the 5h reset shown under their REPL (or /usage) and pass it as --at — that's the authoritative number the agent can't see when both sources are degraded. If they decline, schedule at ceil(reset to next :00) + 2 min (round UP to the next hour) — overshooting starts you slightly late in a fresh window; undershooting burns the old one.
• error (no source) → ask the user for the reset time (/usage) and proceed as if --at.
• No active block / utilization_pct ~0 (user idle >5h): there is no "next reset" — a new window starts with the next message. Run the prompt now (or confirm with the user if it wasn't --now). --now always means run immediately. With --clear, "now" = execute the runner directly (cmd /c tmp\fresh-run.cmd), no schtasks — fresh-session semantics still apply.
• Sanity check: for the authoritative sources, the value already matches the 5h line — no eyeball needed. For the heuristic fallback, always confirm with the user.

Always schedule at reset + 2 minutes. This is load-bearing: one-shot crons can fire up to ~90 s EARLY, which would land the message in the old, exhausted window. +2 min also keeps you off :00/:30 jitter points.

Step 2a — Default mode (same session)

CronCreate one-shot, pinned to the date (load via ToolSearch if deferred):

CronCreate({
  cron: "2 H DoM Mon *",        // local time, reset hour, +2 min
  prompt: "<the user's prompt>",
  recurring: false,
  durable: true                  // reset may be hours away; survive a restart
})

Tell the user: fires only while the REPL is open and idle — leave the session running.

Step 2b — --clear mode (fresh session)

1. If the prompt is inline text, write it to tmp/fresh-prompt.md in the project.
2. Write a runner — never inline the command in /TR (schtasks quoting breaks):

@echo off
cd /d "<project dir>"
type "<abs prompt file>" | claude -p --permission-mode acceptEdits > "tmp\fresh-run.log" 2>&1

Save as tmp\fresh-run.cmd.

3. Schedule it:

schtasks /Create /TN ClaudeFresh /F /SC ONCE /SD MM/DD/YYYY /ST HH:02 /TR "cmd /c \"<abs path>\tmp\fresh-run.cmd\""

4. Tell the user:
   • Output streams to tmp/fresh-run.log; continue interactively later with claude --resume (newest session).
   • acceptEdits is the default; if the plan needs unattended Bash/git, offer --dangerously-skip-permissions as their explicit call.
   • One-shot schtasks don't self-delete: schtasks /Delete /TN ClaudeFresh /F afterwards.
   • Machine must be awake at fire time.

(Non-Windows: same flow, schedule the runner with at / launchd instead of schtasks.)

Quick reference

Common mistakes

• Trusting ccusage's endTime as the reset → it floors the block start to the UTC hour, so it fires up to 59 min EARLY into the old, exhausted window. This was the root cause of the original "fires before reset" bug. Use the resolver; the authoritative source is five_hour.resets_at (what the 5h REPL line shows).
• Scheduling at exactly :00 → early-fire jitter burns the old window. Always +2 min.
• reset_local is already local — the resolver converts. Don't double-convert.
• Inline schtasks /TR command with nested quotes → silently broken task. Use the runner file.
• claude -p without a permission mode → stalls on first edit approval in a headless run.
• CronCreate without durable: true → job dies if the session restarts before reset.
• Fixed task/file names → a second /fresh --clear silently clobbers the first (/F forces). Suffix everything with the <id>.
• Fabricating a reset time when no block is active → there isn't one; the next message defines it.