reminder

Claude Code Reminder

A small reminder manager for Claude Code, made of two parts that work together:

• a /reminder skill to add, list and close reminders in natural language,
• a SessionStart hook that displays a reminder banner (overdue, due today, upcoming) every time a session opens.

Reminders are stored in a plain JSON file (~/.claude/reminders.json). No external dependencies, just Bash and Python 3.

Preview

When a session starts, the hook displays a banner like this:

════════════════════════════════════════════════════════════════
🔔 REMINDERS DUE (1)
════════════════════════════════════════════════════════════════

  ▸ [TODAY · 2026-06-01] my-project
    Check post-deployment metrics

📅 UPCOMING (2)

| Date | Project | Preview |
|------|---------|---------|
| 2026-06-10 | my-project | Re-run the analysis batch |
| 2026-06-20 | global     | Renew the TLS certificate |

→ Full detail: /reminder list   ·   Done: /reminder done <index>
════════════════════════════════════════════════════════════════

Commands

Command	Effect
/reminder:reminder or /reminder:reminder list	List active reminders sorted by date
/reminder:reminder add <date> <message>	Add a reminder
/reminder:reminder done <index>	Mark as done (kept in the file as history)
/reminder:reminder history	List completed reminders

When installed as a plugin, the skill is namespaced as reminder:reminder. If you install it as a standalone project skill instead (see manual install), it is simply /reminder.

Dates accept both absolute (2026-06-16, June 16, 06/16/2026) and relative (tomorrow, in 2 weeks, next Monday) forms. Claude converts them to YYYY-MM-DD before saving.

Installation

As a plugin (recommended)

This repo is both a Claude Code plugin and a single-plugin marketplace. Installing the plugin registers the skill and the SessionStart hook automatically, with no manual settings.json editing.

/plugin marketplace add JeremieSamson/claude-code-reminder
/plugin install reminder@jsamson

Automatic (standalone skill + hook)

git clone https://github.com/JeremieSamson/claude-code-reminder.git
cd claude-code-reminder
./install.sh

The script copies the skill into ~/.claude/skills/reminder/, the hook into ~/.claude/scripts/, then prints the snippet to paste into ~/.claude/settings.json.

Manual

1. Copy the skill:

   mkdir -p ~/.claude/skills/reminder
   cp skills/reminder/SKILL.md ~/.claude/skills/reminder/
   

2. Copy the hook:

   mkdir -p ~/.claude/scripts
   cp hooks/check-reminders.sh ~/.claude/scripts/
   chmod +x ~/.claude/scripts/check-reminders.sh
   

3. Register the hook in ~/.claude/settings.json, under the hooks key:

   {
     "hooks": {
       "SessionStart": [
         {
           "matcher": "",
           "hooks": [
             {
               "type": "command",
               "command": "/home/<user>/.claude/scripts/check-reminders.sh"
             }
           ]
         }
       ]
     }
   }
   

   Adapt the absolute path to your $HOME.

Format of reminders.json

[
  {
    "date": "2026-06-16",
    "project": "my-project",
    "message": "Reminder description"
  },
  {
    "date": "2026-06-01",
    "project": "my-project",
    "message": "A completed reminder",
    "done": true,
    "completed_at": "2026-06-02"
  }
]

The project field is optional. Completed reminders are not deleted: done marks them with done: true and a completed_at date, and they are hidden from the banner and from list. See reminders.example.json.

How the hook works

For a message to be displayed in the terminal (not just injected into the model's context), a SessionStart hook must emit JSON with a systemMessage field. Plain stdout only becomes additionalContext, which is invisible to the user. That is exactly what check-reminders.sh does.

License

MIT, see LICENSE.