Metadata-Version: 2.4
Name: goodmorning-claude
Version: 1.0.0
Summary: Schedule a morning ping to the Claude CLI to trigger the 5-hour usage window (macOS only)
Project-URL: Source, https://gitlab.com/waterjuice/goodmorning-claude
Author: WaterJuice
License-Expression: Unlicense
License-File: LICENSE
Keywords: claude,cli,launchd,macos,scheduler
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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

```bash
pip install goodmorning-claude
```

Or run directly with uv:

```bash
uvx goodmorning-claude install --time 07:05
```

## Quick Start

```bash
# 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

```bash
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](https://unlicense.org/) — public domain.
