goodmorning-claude 1.0.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 a time you choose (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
• 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 run directly with uv:

uvx goodmorning-claude install --time 07:05

Quick Start

# Install the schedule — runs every morning at 07:05
goodmorning-claude install --time 07:05

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