opencode-mobile-push

An OpenCode v2 plugin that notifies your phone when the agent finishes, stops on an error, or is waiting for a permission or an answer. It works with the opencode-mobile app.

Setup

1. Add the plugin to ~/.config/opencode/opencode.json (or opencode.jsonc) and restart OpenCode:

"plugins": ["opencode-mobile-push"]

2. In the app, connect to your OpenCode server, open the bell on the projects screen and turn on notifications for that server.

On first start the plugin creates a pairing key and saves it to ~/.config/opencode/opencode-mobile-push.json (readable only by you). The app reads that key through the OpenCode server, so nothing has to be copied by hand, and every phone that connects to this computer uses the same key. Notifications go through the public relay at https://relay.opencodemobile.app.

To pin a version, use "[email protected]".

OpenCode installs an unpinned plugin once, into ~/.cache/opencode/npm/opencode-mobile-push@latest/, and does not fetch new versions on restart (@latest uses the same folder). To move to a new version, delete that folder and restart OpenCode, or call OpenCode's POST /api/plugin/update with {"targets": ["opencode-mobile-push"]}. If OpenCode logs "relay" and "key" options are required; notifications are off., it is still running 0.2.0 or older; update it this way.

To use your own relay, or a key you choose, pass them as options:

"plugins": [
  {
    "package": "opencode-mobile-push",
    "options": { "relay": "https://<your-relay>", "key": "<pairing key>" }
  }
]

Without npm, copy opencode-mobile-push.js to ~/.config/opencode/plugins/ (OpenCode loads that folder by itself). The settings file works the same way:

{ "relay": "https://<your-relay>", "key": "<pairing key>" }

Options given in opencode.json / opencode.jsonc take precedence over this file.

Options

All default to true.

| Option | Effect | |---|---| | includeTitle | Include the session title and error text (encrypted) | | notifyOnComplete | The agent finished its turn | | notifyOnError | The turn stopped on an error | | notifyOnPermission | The agent is waiting for a permission | | notifyOnQuestion | The agent is waiting for an answer |

When a notification is dealt with somewhere else (the permission or question answered at the computer, the session opened in the TUI, or a new message sent), the plugin tells the phone, which removes the notification and lowers the app badge without showing anything.

Privacy

The relay never sees what a notification says. Two keys are derived from the pairing key with HKDF-SHA256: an auth token the relay knows (and stores only as a hash), and an encryption key it never gets. The project name and session title are sealed with AES-256-GCM and opened only on the phone. The relay sees the kind of event and the session ID.

Subagent sessions are not reported, and the same notification is not sent twice within 15 seconds.

License

MIT