Nag

1. State File

Create memory/nag-state.json in the workspace:

{
  "date": "2026-02-15",
  "reminders": {}
}

The date field triggers automatic daily resets — when today's date differs from the stored date, all reminders reset to unconfirmed.

2. Reminder Config

Create nag-config.json in the workspace root:

{
  "reminders": [
    {
      "id": "morning-supplements",
      "label": "morning supplements",
      "cronFirst": "0 8 * * *",
      "nagAfter": "09:00",
      "confirmPatterns": ["taken", "done", "took them", "did it", "yes"],
      "tone": "friendly but persistent, escalate to ALL CAPS drama after 3 nags",
      "messages": {
        "first": "Time for morning supplements!"
      }
    }
  ]
}

Fields:

| Field | Required | Description | |-------|----------|-------------| | id | yes | Unique identifier, used as key in state file | | label | yes | Human-readable name for display | | cronFirst | yes | Cron expression for initial reminder (create a cron job for this) | | nagAfter | yes | Time (HH:MM, 24h) after which heartbeat nags begin | | confirmPatterns | yes | Array of phrases that mark the reminder as done (case-insensitive, substring match) | | tone | no | Personality guidance for generating nag messages. If absent, use a neutral friendly tone. The model has creative liberty to vary the wording each nag. | | messages.first | no | Text sent by the cron job for the initial reminder. If absent, generate from label + tone. | | messages.nag | no | Suggested nag text. If absent, generate contextually from label + tone + nagCount. | | messages.escalate | no | Suggested text after 3+ ignored nags. If absent, generate with increased urgency from tone. | | days | no | Array of weekday names to restrict when this reminder fires (e.g. ["monday", "wednesday", "friday"]). Omit for every day. |

For more examples, see references/config-examples.md.

Message generation: When messages.nag or messages.escalate are absent, generate them on the fly using the label and tone fields. Vary the wording each time — don't repeat the same nag verbatim. Use nagCount to calibrate urgency: low count = gentle, 3+ = escalated.

3. Wire Up Cron + Heartbeat

For each reminder, create a cron job that fires messages.first at the cronFirst schedule.

In HEARTBEAT.md, add a nag check block:

```