Quickstart

Follow these steps to install HowlAlert, connect your account, and start receiving usage alerts for your Claude Code sessions.

1. Download HowlAlert

HowlAlert is available on the Mac App Store and iOS App Store. Download it on any device you want to receive alerts on.

The watchOS companion app installs automatically when your Apple Watch is paired with an iPhone that has HowlAlert installed.

Open HowlAlert and tap Sign In with Apple. This creates your secure account instantly — no passwords, no email verification. Your Apple ID ties all your devices together so alerts reach every one of them.

3. Grant File Access (macOS)

On first launch, HowlAlert asks permission to read ~/.claude/ so it can monitor your Claude Code sessions. Click Allow when prompted.

HowlAlert uses FSEvents to watch for file changes in real time, so your usage data is captured the moment a session updates.

4. Set Your Thresholds

Open Preferences and configure the alert thresholds that matter to you:

Daily Cost — Get notified when your daily spend exceeds a dollar amount (default: $5.00)
Token Count — Alert when total tokens used today exceed a count (e.g., 100,000)
Session Count — Alert after a number of sessions in one day

You can enable one, two, or all three threshold types. Each one is evaluated independently.

5. Use Claude Code Normally

That's it for setup. HowlAlert runs silently in the macOS menu bar, tracking usage from your local Claude Code sessions in the background. Usage data is sent securely to the HowlAlert API worker where it's aggregated and checked against your thresholds.

6. Receive Alerts

When a threshold is exceeded, you'll receive a push notification on all your registered devices — Mac, iPhone, and Apple Watch. Tap the notification to open HowlAlert and see your current usage breakdown.

What's Next?

Configuration — Detailed settings and threshold options
Troubleshooting — Solutions if something isn't working
Architecture — Understand how all the pieces connect