Reminder Telegram

Obsidian plugin that sends Telegram notifications when your tasks reach their deadline. Supports date-only deadlines (checked on an interval), exact-time deadlines (precise scheduler), upcoming reminders, and recurring tasks.

Features

• Frontmatter + inline tasks — YAML scheduled/due fields, - [ ] lines with 📅, due::, scheduled::, starts::, and plain dates
• Exact-time reminders — Reminder-plugin @ syntax and Kanban @@ syntax fire at the precise minute, with configurable lead time
• At-time scheduler — a timer wakes up at each deadline instead of waiting for the next interval check
• PC-off catch-up — missed notifications (at-time, overdue, upcoming) fire when the app re-opens, within a configurable window
• Upcoming reminders — heads-up for tasks due in the next N days, with its own templates
• Recurring tasks — 🔁 every … syntax auto-advances a completed task to its next occurrence and re-opens the checkbox
• Telegram integration — bulk digests or individual messages, markdown formatting, 4096-char truncation
• Duplicate prevention — per-task notified state persisted across sessions
• Task sidebar — overdue / due-today / upcoming views with time-scope and tag filters
• Template editor UX — clickable variable chips, character counters, live preview
• Status bar — click to check immediately; shows the last check time

Installation

From Obsidian Community Plugins

1. Settings → Community plugins → Browse
2. Search for "Reminder Telegram"
3. Install and enable

Manual

1. Clone the repo or download the latest release
2. Copy main.js, manifest.json, styles.css into your vault's .obsidian/plugins/obsidian-reminder-telegram/
3. Reload Obsidian and enable the plugin

Requires Obsidian 1.7.2+ (minAppVersion).

Setup

1. Create a bot: in Telegram, message @BotFather, send /newbot, follow the prompts, copy the token.
2. Get your chat ID: message @userinfobot, send /start; it replies with your numeric chat ID.
3. Configure the plugin: paste the token and chat ID under Settings → Reminder Telegram. The settings tab walks through these steps too.
4. Send a test notification via the "Send test" button to verify.

Task syntax

YAML frontmatter

A note with a scheduled or due field and --- delimiters becomes a task. The task text is the note's base name, or the first heading after the frontmatter if one exists.

---
status: open
scheduled: 2024-12-25
tags:
    - task
---

# My Task

Complete this task by Christmas

• status: open / in-progress = incomplete; done / completed / cancelled / archived = completed (a completedDate field also marks it done)
• scheduled / due: YYYY-MM-DD (date-only) or YYYY-MM-DDTHH:MM (exact time)
• tags: used for sidebar tag filtering (not required for recognition)

Inline tasks

- [ ] Complete project by 📅 2024-12-25
- [ ] Review notes due:: 2024-12-20
- [ ] Meeting scheduled:: 2024-12-15

Accepted date formats: YYYY-MM-DD, MM/DD/YYYY, DD-MM-YYYY, with optional times (YYYY-MM-DDTHH:MM or YYYY-MM-DD HH:MM). Lines inside fenced code blocks are ignored; [x]/[X] tasks are skipped.

Exact-time syntax

Reminder-plugin @ syntax (toggle: Reminder syntax):

- [ ] Call Grandma @2026-07-22 12:30
- [ ] Call Grandma (@2026-07-22 12:30)
- [ ] Buy milk (@2026-07-22) # no time → date-only

Kanban-plugin syntax (toggle: Kanban syntax):

- [ ] Call Grandma @2026-07-22 @@14:30 # date + time
- [ ] Buy milk @2026-07-22 # no time → date-only

Reminder syntax owns @YYYY-MM-DD HH:MM; Kanban owns @YYYY-MM-DD @@HH:MM and bare @YYYY-MM-DD.

Recurring tasks

Append 🔁 every … to an inline task (works with any date syntax, including the full reminder form):

- [ ] Water plants 📅 2026-07-22 🔁 every day
- [ ] Call Grandma (@2026-07-31 09:00 🔁 every week on Sunday)
- [ ] Pay rent 📅 2026-08-01 🔁 every month
- [ ] Renew license 📅 2026-07-22 🔁 every year

When you complete a recurring task (- [x]), the plugin rewrites the line: the checkbox re-opens and the date advances to the next occurrence — task text and metadata are preserved. Overdue recurring tasks advance until the next occurrence is in the future. Toggle: Recurring tasks (default on).

Notification behavior

When do notifications go out:

1. Interval checks — every Check interval minutes (default 30) and on manual triggers. Handles date-only tasks: due today, overdue, and upcoming.
2. At-time scheduler — datetime tasks fire at deadline − lead time via a precise timer, re-armed on vault changes, workspace changes, and app resume.
3. PC-off catch-up — on the next check after the app re-opens, missed notifications fire if they fall within the catch-up window; anything older is silently dropped.

Catch-up window (Catch-up window (minutes), default 60) applies to:

• at-time tasks: fires whose scheduled time is within the window
• overdue tasks: deadline within the window (datetime tasks by exact timestamp; date-only tasks from the end of their day)
• tasks that were upcoming while the app was closed and became overdue within the window

Tasks due today are never gated. A window of 0 disables the gate and past behavior applies (all overdue tasks are always notified).

Upcoming reminders (Upcoming reminders + Days ahead for upcoming, default 1): tasks due in the next N days (tomorrow onward) get a heads-up with their own templates. Due/overdue notifications share the per-check budget (Max tasks per check).

Strict time mode: when enabled, datetime tasks are handled only by the at-time scheduler — interval checks skip them entirely (default off, so the interval stays as a safety net).

Sidebar

Open via the 🔔 ribbon icon or the "Toggle sidebar" command.

• Overdue — past deadline
• Due Today
• Upcoming — next N days (same Days ahead setting)

Filters: today (hide upcoming), week (cap upcoming at 7 days), tag (intersect by frontmatter tag), clear. Relative dates are shown (Today / Yesterday / Tue / in 3 days). Clicking a task opens the file and scrolls to the task line (or heading).

Commands

Message templates

Variables:

• Digest templates (multi-task): {count}, {tasks}
• Individual templates: {taskName}, {fileName}, {deadline}, {filePath}, {taskId}
• Upcoming uses its own digest + individual templates with the same variables

Bulk messages send when more than one task is due; otherwise an individual message is sent. Messages are truncated at Telegram's 4096-character limit (markdown-safe cutoff when formatting is on).

The template editor provides clickable variable chips, per-field character counters (warn at 80% of 4096), and a live preview panel with sample data (toggle: Live preview).

Markdown formatting: enable in settings for *bold*, _italic_, `code`, [links](https://example.com). Literal characters the parser rejects cause Telegram to return an error — keep unescaped */_ usage minimal.

Settings

Development

npm install
npm run dev       # watch mode
npm run build     # type-check + esbuild
npm run lint
npm test          # vitest (mocked obsidian + Telegram HTTP)
npm run test:coverage

Planned

Ideas that are not implemented yet:

• Advanced scan filters — exclude specific folders or patterns from the scan
• Explicit timezone handling — per-task or per-vault timezone management for exact-time deadlines (currently local time)
• Snooze / postpone — inline Telegram interaction to push a task's deadline

Contributing

Pull requests welcome — open an issue first for significant changes.

License

BSD-0-Clause. See LICENSE.