nudge

name	nudge
description	Nudge the user with time-based reminders (stopping times, meetings, break suggestions). Surfaces via hook on prompt submission -- requires human interaction to fire. NOT for process monitoring or job polling -- use `sleep` in Bash instead.

Nudge

Human-facing reminder system for managing focus and pacing. Nudges are stored in SQLite and surface via hook when due.

When to Use

Proactively set nudges when:

• User mentions a stopping time ("stop me at 11", "I need to wrap up by 5")
• User mentions a deadline or meeting ("standup in 30 minutes")
• A long focus session (2+ hours) is underway without breaks
• User asks for a reminder explicitly

Do NOT use nudge for:

• Tasks Claude will complete in the current turn
• Information that should go in memory instead
• Process monitoring (e.g., "check if the build finished", "see if the pipeline completed"). Nudges require user input (prompt submission) to fire, so they cannot check on running processes. Use sleep <seconds> in Bash instead -- it blocks inline and resumes without requiring user interaction.

Tools

Scripts are located at hooks/:

Adding a Nudge

python3 hooks/add_alert.py "<time>" "<message>"

Time formats:

• HH:MM - Today at that time (e.g., 23:00)
• YYYY-MM-DD HH:MM - Specific datetime
• +30m - 30 minutes from now
• +2h - 2 hours from now

Acknowledging a Nudge

When a nudge has been addressed, dismiss it:

python3 hooks/ack_alert.py <id>

Viewing Nudges

sqlite3 hooks/alerts.db "SELECT id, due_at, message FROM alerts WHERE acknowledged = 0"

Message Format

Messages are notes-to-self for Claude. Include:

1. Reason - Why this nudge was set
2. Action - What to do when it fires

Format: reason - action to take

Examples

User asked to stop at 11 PM - wrap up current work and suggest break
User mentioned standup in 30m - remind to prep notes
2 hours on debugging session - check if stuck, suggest break
Deployment window opens at 14:00 - remind user to run deploy script

When Nudges Fire

Due nudges appear in the system-reminder on each prompt submission. When a nudge fires:

1. Read the message to understand context and action
2. Take the specified action (remind user, suggest break, etc.)
3. Acknowledge the nudge so it doesn't repeat

Database Schema

CREATE TABLE alerts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    due_at TEXT NOT NULL,           -- "YYYY-MM-DD HH:MM"
    message TEXT NOT NULL,          -- reason - action
    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
    acknowledged INTEGER DEFAULT 0  -- 0=pending, 1=done
)

Location: hooks/alerts.db