macotron.reminders

List, add, and check off reminders in the Reminders app, across every list and account on the Mac.

const items = await macotron.reminders.list({ days: 1 });
macotron.menubar.status("reminders", {
  title: items.length ? items[0].title : "Reminders",
  sfSymbol: "checklist",
  menu: items.map((item) => ({
    title: item.title,
    onClick: () => macotron.reminders.complete(item.id),
  })),
});

Reading

list(opts?: { days?: number; completed?: boolean }): Promise<Array<{ id, title, due, completed, list }>>

Reminders from every list. The fetch runs off the main thread.

By default the result holds only incomplete reminders. With completed: true it holds only completed ones.

days keeps reminders that are due within that many days from now, plus overdue ones, plus reminders with no due date. Omit it to get every reminder.

Each row has id, title, due (milliseconds since 1970, or null when there is no due date), completed, and list (the name of the list it is in).

Writing

These calls return their result right away, not a promise.

add(row: { title: string; due?: number; list?: string }): { ok: boolean; id?: string; error?: string }

Creates a reminder and returns { ok: true, id }. due is in milliseconds since 1970 and is kept to the minute. list is a list name, matched without regard to case. When it is omitted or matches no list, the reminder goes in your default list.

Returns { ok: false, error } when the title is empty ("title required"), when Macotron has no access ("unauthorized"), or when the save fails.

complete(id: string, on?: boolean): { ok: boolean; error?: string }

Marks the reminder done. Pass false for on to mark it not done again. Returns { ok: false, error: "not found" } for an unknown id, and "unauthorized" without access.

Macotron needs Reminders access. The first call asks macOS to show the permission prompt: list() resolves with [] and add() returns "unauthorized" while the user decides. If access is denied, turn it on in System Settings → Privacy & Security → Reminders.