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 a time of your choosing (default 07:05), anchoring the window to the start of 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
  • Configurable time — pick any hour and minute
  • 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 run directly with uv:

uvx goodmorning-claude install --time 07:05

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 StartCalendarInterval set to your chosen hour and minute, 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.