Skip to content

goodmorning-claude

A tiny macOS scheduler that pings the claude CLI each morning so the 5-hour usage window starts at a predictable wall-clock time.

Why?

Claude's usage allowance is measured over a rolling 5-hour window that begins on your first interaction of the day. If your first real prompt lands at 09:37, your window closes at 14:37 — right in the middle of the afternoon. goodmorning-claude fires a throwaway hi prompt at times of your choosing (default 07:05, 12:10 and 17:15), anchoring fresh windows across your work day.

Features

  • Set-and-forget scheduling — one command installs a launchd LaunchAgent
  • Wall-clock firing — uses StartCalendarInterval so it fires at the actual time, not relative to boot
  • One or many times — schedule a single ping or several through the day (default 07:05, 12:10, 17:15)
  • Manual trigger — fire the ping on demand with run
  • Resilient PATH — resolves claude at install time so the schedule works even if your shell init is what normally puts it on PATH
  • Zero dependencies — stdlib only

Requirements

  • macOS — this tool is macOS-only. The CLI refuses to run on any other platform.
  • Python 3.12+
  • claude CLI on your PATH — authenticated at least once

Quick Start

Install

pip install goodmorning-claude

Or with uv:

uv tool install goodmorning-claude

goodmorning-claude must be installed persistently — do not schedule it via uvx. A uvx run's executable lives in uv's cache, which uv cache prune can delete at any time, and the schedule bakes that path into the LaunchAgent. install detects this and refuses rather than leaving you with a schedule that stops firing months later.

Schedule the morning ping

goodmorning-claude install --time 07:05

Check status

goodmorning-claude status

See the Usage page for full details on all commands.

How It Works

When triggered, goodmorning-claude runs claude -p "hi" — a non-interactive print-mode invocation that opens your 5-hour usage window and exits immediately. Scheduling is delegated to launchd: install writes a plist to ~/Library/LaunchAgents/com.waterjuice.goodmorning-claude.plist with a StartCalendarInterval entry for each chosen time, then loads it with launchctl bootstrap.

Credentials after reboot

The LaunchAgent runs inside your user's GUI session, so the scheduled ping has the same credential access as your interactive claude shell. Claude Code's OAuth refresh token lives in your login keychain, which unlocks automatically when you log in — no re-auth needed per reboot.

Sleep and missed fires

launchd replays the most recent missed StartCalendarInterval when your session becomes active again, so a laptop that sleeps overnight fires on time in the morning.