@cioinside/opencode-alarm

An opencode plugin that lets the agent set a timer/alarm. After the specified delay, the agent receives a notification containing an optional note — no user prompt required. This lets a long-running agent "go to sleep" and wake itself up to resume work, polling, file watching, or any task that needs a delay.

Tools

The plugin exposes three tools that the agent can call:

set_alarm

Set an alarm. After duration_seconds elapses, the agent receives a session message like:

[alarm] 🔔 alarm fired (set 3600s ago, id=42):

Verify the staging deployment finished and report any test failures.

The text comes from the optional note parameter. If note is omitted, a generic "alarm fired" line is sent.

{
  "duration_seconds": 3600,
  "note": "Verify the staging deployment finished and report any test failures."
}

list_alarms

List active (not yet fired, not cancelled) alarms. Includes a short preview of the note.

cancel_alarm

Cancel a pending alarm by id. Already-fired alarms cannot be cancelled (the message has already been delivered).

Persistence

Alarms live in a SQLite database at ~/.config/opencode/alarm/alarms.db. A background poller runs every 5 seconds while the plugin is loaded (TUI or opencode run). The poller checks fire_at_ms <= now and fires the alarm by sending session.promptAsync to the session that set it.

If opencode is restarted, alarms survive — the next load picks up where it left off and any alarms that became due while opencode was down will fire on the next poller tick.

Storage

Path	Purpose
~/.config/opencode/alarm/alarms.db	SQLite alarm queue
~/.config/opencode/alarm/alarm.log	Plugin log (one line per alarm set/fire/fail)

Install

// ~/.config/opencode/opencode.jsonc
{
  "plugin": [
    "opencode-alarm"
  ]
}

Then restart opencode. The first run will create ~/.config/opencode/alarm/ automatically.

What it does NOT do

• Does not make sound. The notification is a session message — the agent reads it, the user sees the agent respond.
• Does not survive a database wipe. If you delete alarms.db, alarms are gone.
• Does not auto-cancel cancelled-by-restart sessions. If a session is renamed or restarted before its alarm fires, the alarm delivery fails with "Session not found" and is marked fired (so it doesn't pile up forever). Set a fresh one in the new session if you need it.

License

MIT