Nudge

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:

• Reason - Why this nudge was set
• 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:

• Read the message to understand context and action
• Take the specified action (remind user, suggest break, etc.)
• 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