archibate Urgent Notify
Overview
When user is AFK (Away-From-Keyboard), not watching Claude. We need to send a notification on urgent events to call user back.
AFK Indicators
- User is not responding for more than 10 minutes
- Claude asked an critical question, but user didn't response in 10 minutes
- All recent messages are system messages (e.g.
<task-notification>) - Claude is waiting for a background task
- Claude is periodically waiting and checking things
When to Use
- User is AFK and:
- Urgent exception that Claude should not solve on its own
- Critical decision that require human interception
- User requested to notify them when some condition met or task complete
- User requested to send progress report every X minutes
- Any unexpected emergence blocking progress
When NOT to Use
- User is obviously not AFK (chatting with Claude interactively)
- Not very urgent exception that Claude can easily recover from
Notification Methods
Determine which to use by checking environment:
# Check for Linux desktop session
echo $DISPLAY
# Check for ntfy.sh topic
echo $NTFY_SH_PRIVATE_TOPIC
# Check for macOS
uname -s
Decision logic:
| Condition | Method |
|---|---|
$DISPLAY non-empty |
Linux desktop (notify-send) |
uname -s = Darwin |
macOS (terminal-notifier) |
$NTFY_SH_PRIVATE_TOPIC non-empty |
Remote via ntfy.sh |
| None of the above | Fallback: write to /tmp/claude-urgent-notify |
Linux Desktop
notify-send -a "claude" -u critical "Claude" "<message>"
macOS
terminal-notifier -title "Claude" -message "<message>"
Remote/SSH via ntfy.sh
Ask the user to set up a private topic in environment:
export NTFY_SH_PRIVATE_TOPIC="your-secret-topic-name"
Send notification:
curl -s -d "<message>" "https://ntfy.sh/$NTFY_SH_PRIVATE_TOPIC"
⚠️ Privacy Warning: ntfy.sh topics are public. Anyone who knows your topic name can subscribe. Never include sensitive content like API keys, passwords, or confidential data in notifications.
Example Scenarios
Training Job Failed
User started a 4-hour training job via pueue and went AFK. Task failed after 2 hours:
pueue status shows task #5 status: Failed, exit code: 1
→ Send urgent notification: "Training job #5 failed with exit code 1. Check logs."
Deploy Condition Met
User said "notify me when the deploy is live". Long-waits polling detected success:
curl check shows deploy status: success
→ Send urgent notification: "Deploy is live on staging!"
Critical Decision Needed
Background task encountered ambiguous situation requiring human input:
Found 3 conflicting config files. Cannot auto-resolve.
→ Send urgent notification: "Need decision: multiple config files found, which to use?"