Reminders

A minimal CLI that fires desktop notifications for YAML-defined reminders. No app, no UI — just files and notify-send.

Your reminders are plain YAML files you own: keep them in a dotfiles repo, edit them in your editor, diff them in git. A systemd timer runs the check hourly and notify-send does the rest.

• One-time, recurring and fixed-schedule triggers — a date, a last + freq interval, or a fixed weekly/monthly/yearly slot.
• Early notifications — get pinged a configurable while before the due date.
• No nagging — an overdue reminder re-fires at most once per its own precision, and reminders done bumps or silences it.
• --summary — a colored overview of everything late, soon and upcoming.
• Fails soft — a bad entry is skipped with a warning, never taking the run down with it.

Installation

pipx / pip (from source):

pipx install git+https://github.com/danisztls/reminders
# or
pip install git+https://github.com/danisztls/reminders

Arch Linux (AUR):

yay -S reminders-git

Setup

On first run, reminders auto-creates $XDG_CONFIG_HOME/reminders/config.yaml with a default reminders file:

# $XDG_CONFIG_HOME/reminders/config.yaml
paths:
  - "~/.config/reminders/reminders.yaml"

Add more paths to load reminders from multiple files:

paths:
  - "~/.config/reminders/personal.yaml"
  - "~/.config/reminders/work.yaml"
  - "~/notes/reminders.yaml"

day_start

By default a whole-day reminder (a bare date like next: 2026-07-01, with no time) becomes due at midnight, so you get pinged about "tomorrow's" tasks the moment the clock rolls over — often while you're still up and heading to bed. Set day_start to the hour (0–23) at which a new day should really begin, and whole-day reminders wait until then:

paths:
  - "~/.config/reminders/reminders.yaml"
day_start: 6 # whole-day reminders hold until 06:00

This only affects bare dates. A reminder with an explicit time (next: 2026-07-01T01:30) or an hourly freq still fires exactly when scheduled, so add a time to next if you want a specific whole-day item to ignore day_start. The default is 0 (midnight), which preserves the old behavior.

Reminder format

Each reminder file is a YAML list of entries. The annotated reminders.template.yaml is the complete reference for every field, format, and option — copy it as a starting point. A minimal entry:

- name: "Dentist appointment"
  desc: "Call to confirm beforehand."
  next: 2026-06-15

Every entry needs a name and exactly one trigger — next (one-time), last + freq (recurring), yearly, monthly, or weekly — plus optional desc and early. See the template for the full field reference and worked examples of each.

Usage

reminders

Fires desktop notifications for any overdue reminders.

reminders --summary

Pretty-prints all reminders grouped by status:

• Late (red) — trigger date is past
• Soon (yellow) — due within the next 7 days
• Future (white) — everything else

Each group shows the due date, name, and description (if set), sorted by date.

reminders done "water the plants"

Marks a reminder as completed. For recurring reminders this rewrites the entry's last: line to today (preserving the rest of the file untouched); for one-time and fixed-schedule reminders it silences the current occurrence. Matching is case- and punctuation-insensitive. Run reminders done without a name to pick from a numbered menu of all reminders, sorted soonest-first.

reminders --config /path/to/config.yaml

Uses an alternate config file (works with all commands).

The hourly check never modifies your reminder files — only reminders done edits them, and only the matched last: line.

Notification state (which occurrences have already been announced) lives in $XDG_DATA_HOME/reminders/state.json and is pruned of stale entries automatically. Deleting it is harmless — it only means already-notified reminders may notify once more.

Malformed files or entries don't abort the run: they are skipped with a warning on stderr (visible in journalctl), and unreadable files additionally trigger a desktop notification at most once a day.

Automation

Install the included systemd user units to run reminders hourly in the background:

cp reminders.service reminders.timer ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now reminders.timer

Check status:

systemctl --user status reminders.timer
journalctl --user -u reminders.service

Requirements

• Linux or BSD with a running notification daemon (Dunst, Mako, GNOME/KDE's built-in, …)
• notify-send (provided by libnotify on most distros)
• Python 3.11+

Development

uv sync          # install dependencies
uv run reminders # run from the checkout
uv run pytest    # run the test suite

The whole tool is a single file, reminders.py.

License

GPLv3 — see LICENSE.