goodmorning-claude 1.2.0

Schedule a morning ping to the Claude CLI to trigger the 5-hour usage window (macOS only)

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.

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 you choose (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)
• 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

Installation

pip install goodmorning-claude

Or with uv:

uv tool install goodmorning-claude

Install it persistently — don't schedule it with uvx. A uvx run's executable lives in uv's cache, which uv cache prune is free to delete, and the schedule bakes that path into the LaunchAgent. install detects this and refuses, rather than handing you a schedule that quietly stops firing months later.

Quick Start

# Install the schedule — defaults to 07:05, 12:10 and 17:15 daily
goodmorning-claude install

# ...or pick your own times (space-separated)
goodmorning-claude install --time 07:05 12:10 17:15

# Check it's installed
goodmorning-claude status

# Trigger the morning ping manually
goodmorning-claude run

# Remove the schedule
goodmorning-claude uninstall

How It Works

When triggered, goodmorning-claude shells out to 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 LaunchAgent plist to ~/Library/LaunchAgents/com.waterjuice.goodmorning-claude.plist with a StartCalendarInterval entry for each chosen time, then loads it with launchctl bootstrap gui/<uid>.

Credentials after reboot

LaunchAgents run 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. If you use a separate "Login Keychain" password that doesn't match your account password, the scheduled ping will fail silently until you unlock the keychain.

What if the Mac is asleep or off at fire time?

launchd replays the most recent missed StartCalendarInterval as soon as your user session becomes active again. So a laptop that sleeps overnight fires on time in the morning; a Mac that was off at 07:05 fires when you log in.

Development

make dev        # Set up development environment
make check      # Run linting and type checking
make format     # Auto-format code
make build      # Build wheel and docs

Licence

Released under the Unlicense — public domain.