OpenCode Reminders for v2

Schedule one-time or recurring prompts in OpenCode sessions. This is a maintained v2 fork of Dmitry Zelenkovsky's opencode-reminders; thank you to Dmitry for creating the original plugin. The original and this fork are MIT licensed.

This branch is an OpenCode v2 port, not the v1 npm release. It has not been published as v2; do not assume bun install opencode-reminders installs this version. It has no runtime dependencies. For an existing installation, make a reviewed local copy of this repository available to the server and register its entry point in the v2 configuration. For example, relative to the configuration directory:

{
  "plugins": [
    { "package": "./plugins/opencode-reminders", "options": {
      "max_reminders_per_project": 50,
      "min_interval_seconds": 30
    } }
  ]
}

Restart the server after installing or changing the plugin. Check the host's own v2 plugin configuration and loading rules before deployment; no automatic migration or deployment is provided here. Do not load this port on a v1 server.

Use

Ask the assistant to schedule, list, pause or remove a reminder. The plugin registers reminderadd, reminderlist, reminderpause and reminderremove. Intervals are at least 30 seconds. Reminders are persisted per project under .opencode/reminders/; prompts are delivered to their original session. Paused reminders do not automatically resume.

reminderadd defaults to an action; execution: "monitor" is for an explicitly authorised, bounded routine check. Monitor mode retains the original session and captured agent, with ordinary model and permission resolution; it does not guarantee a cheaper model or authorise follow-on work. Both actions and monitors pause on a failed or unverifiable execution, including provider usage-limit failures; inspect the session before removing and recreating a reminder. The legacy max_consecutive_failures option is ignored.

Important limits

• Prompts use queued delivery rather than interrupting an active turn. Session busy status comes from observed events; it is not a status query.
• The v2 API has no per-prompt agent argument. The plugin never switches a session agent: a captured-agent mismatch pauses the reminder. Agent verification and prompt admission are not atomic, so another actor can still change the session agent between them. Legacy reminders without a captured agent use the current session agent. Completion is conservatively checked against all messages after the admitted user message; intervening user messages, incomplete or failed assistant messages, and missing or unsuccessful terminal idle markers pause the reminder rather than crediting it.
• Server-side toast notifications are unavailable; legacy notification options are ignored.
• Before admission, the occurrence is durably paused as an in-flight guard. A successful, unambiguous completion clears it; a process crash, reload, admission error or ambiguous completion leaves it paused for manual inspection, even if no prompt was actually admitted. This favours avoiding duplicate submissions over guaranteed delivery and is not exactly-once delivery. Storage writes are not fsynced: an OS or power failure may lose the guard and allow a duplicate. Cancellation cannot retract a prompt already admitted. Leases and guards require same-host local filesystem operations, not distributed filesystems; a stale recovery guard may require manual cleanup.
• Reminders are best-effort and depend on the server running. They are not guaranteed OS-level alarms.

See VENDORED.md for the v2 mapping, behavioural gaps and the provenance of this port. The focused tests are not a full replacement for the original v1 test suite or proof of compatibility with every v2 server build.

Development

Run bun test with Bun. The tests use fake hosts and temporary storage; they do not exercise a live provider or deploy the plugin.