67 lines
3.0 KiB
Markdown
67 lines
3.0 KiB
Markdown
---
|
||
name: remind
|
||
description: >
|
||
Create, list, edit, enable, disable, and remove recurring or one-time reminders.
|
||
Triggers on: "/remind", "remind me", "set a reminder".
|
||
---
|
||
|
||
# /remind
|
||
|
||
Reminders are stored in SQLite (`db/reminders.sqlite`) and delivered by `remind_send.py`,
|
||
which runs every minute from the nanobot user crontab, directly to Telegram, outside the agent.
|
||
Reply to the user in their own language.
|
||
|
||
## Natural language → command mapping
|
||
|
||
| User says | Command |
|
||
|-----------|---------|
|
||
| "every day at 9" / "every weekday at 9:30" | `add --cron "0 9 * * *"` |
|
||
| "on 2026-06-15 at 18:00" / "once at …" | `add --at "2026-06-15T18:00:00"` |
|
||
| "randomly 2× between 08:00 and 20:00" | `add --random-times-per-day 2 --random-window 08:00-20:00` |
|
||
| "what reminders arrived today / since when" | `delivered [--since YYYY-MM-DD]` |
|
||
| "what goes out today / tomorrow / this week" | `upcoming [--date YYYY-MM-DD \| --days N]` |
|
||
| list all reminders | `list` |
|
||
|
||
For the full flag reference of any command, run:
|
||
|
||
```sh
|
||
uv run skills/remind/scripts/remind_cli.py --help
|
||
uv run skills/remind/scripts/remind_cli.py <command> --help
|
||
```
|
||
|
||
## Behavioral contract
|
||
|
||
**`list`** returns readable text. Each reminder:
|
||
|
||
```
|
||
#<id> text [enabled|disabled]
|
||
cron: 0 9 * * *
|
||
at: 2026-06-15T18:00:00
|
||
random: 2× daily 09:00–21:00 (1-5) from 2026-06-01
|
||
```
|
||
|
||
An empty store prints `(no active reminders)`.
|
||
|
||
**Mutations** (`add`, `edit`, `remove`, `enable`, `disable`) return JSON: `{"added": …}`, `{"edited": …}`, etc. Errors go to stderr with a non-zero exit code.
|
||
|
||
**Selecting a reminder:** `edit`, `remove`, `enable`, `disable` accept `--keyword` (case-insensitive substring) or `--id` (exact). An ambiguous keyword match returns `{"error": "ambiguous", "matches": […]}` — retry with `--id <n>`. Run `list` to see ids.
|
||
|
||
**`delivered`** reads the `reminder_fires` table (delivered rows only, Prague local time). Defaults to today; `--since YYYY-MM-DD` widens the window. The agent never sees deliveries happen — this is the only window into them.
|
||
|
||
**`upcoming`** returns readable text: each scheduled fire as `YYYY-MM-DD HH:MM #id text (type)`, sorted by time. It shows the *plan* (computed from the schedules), not actual deliveries — use `delivered` for those. Defaults to the rest of today; `--date` shows one whole day, `--days N` the next N calendar days. An empty window prints `(nothing scheduled in this window)`.
|
||
|
||
**`remove`** is a soft delete.
|
||
|
||
## Editing reminders
|
||
|
||
**To fix or change wording:** use `edit --id <n> --text "…"` (get the id from `list`),
|
||
or `edit --keyword <kw> --text "…"`.
|
||
**NEVER remove + re-add a reminder just to change its text** — that loses the delivery history and changes the id.
|
||
|
||
Use `--replace-schedules` (with at least one new `--cron`/`--at`/`--random-*`) only when you need to change the *schedule*, not the text.
|
||
|
||
## Environment
|
||
|
||
- `REMIND_DB` — override SQLite path (used in tests).
|
||
- Scripts run via `uv run` (PEP 723 headers declare their dependencies).
|