opencode-helm-studio-notifier

OpenCode plugin that sends HMAC-signed webhooks to the Helm Studio backend when sessions complete, error, or need user input. Enables mobile push notifications for AI agent session events via the Helm Studio mobile app.

How It Works

This plugin is one piece of a three-part system:

1. This plugin runs inside OpenCode on your dev machine. It listens for session events and sends signed webhooks to the backend.
2. Helm Studio Backend receives webhooks, verifies HMAC signatures, and fans out push notifications to subscribed devices via Expo Push Service.
3. Helm Studio Mobile App (iOS/Android) connects to your OpenCode server, subscribes to notifications, and lets you monitor sessions, answer questions, and approve permissions from your phone.

OpenCode (your machine)
  │
  │  session.idle / session.error / question.asked / permission.asked
  │
  ▼
Plugin (this repo)
  │  Signs payload with HMAC-SHA256
  │  POST /webhooks/opencode
  ▼
Helm Studio Backend
  │  Verifies signature, deduplicates, rate-limits
  │  Looks up device subscriptions for this server
  ▼
Expo Push Service
  │
  ▼
Helm Studio App (iOS/Android)
  │  Push notification with session details
  │  Tap to open session, approve permissions, answer questions

The mobile app auto-discovers this plugin's config by reading ~/.config/opencode-helm-studio-notifier/config.json from the OpenCode server filesystem. It uses the serverId and hmacSecret to create a subscription with the backend, proving it's authorized to receive notifications for that server.

Install

From npm

Add to your opencode.json or opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helm-studio-notifier"]
}

Local Development Install

1. Install dependencies in the plugin source directory:

cd /path/to/opencode-helm-studio-notifier
bun install

2. Create a plugin file in your project's .opencode/plugins/ directory that re-exports the plugin:

// .opencode/plugins/helm-studio-notifier.ts
export { HelmStudioNotifier as default } from "/absolute/path/to/opencode-helm-studio-notifier/src/index.ts";

3. Start a new OpenCode session — the plugin will auto-register with the backend and save credentials to ~/.config/opencode-helm-studio-notifier/config.json.

Using a local backend? Create the config file before first run to point at your local instance:

mkdir -p ~/.config/opencode-helm-studio-notifier

// ~/.config/opencode-helm-studio-notifier/config.json
{
  "notifierUrl": "http://localhost:3000/webhooks/opencode"
}

Configuration

All configuration is read from ~/.config/opencode-helm-studio-notifier/config.json. On first run, the plugin auto-registers with the backend and writes serverId and hmacSecret to this file automatically.

Important: notifierUrl must be the full webhook endpoint URL including the path (e.g. /webhooks/opencode). The plugin sends webhooks directly to this URL as-is. Registration uses the same base origin but replaces the path with /servers/register.

{
  "notifierUrl": "https://helm-studio-server.publicker.dev/webhooks/opencode",
  "serverId": "auto-generated-uuid",
  "hmacSecret": "auto-generated-64-hex-chars",
  "enabledEvents": ["session.idle", "session.error", "question.asked", "permission.asked"],
  "timeoutMs": 5000,
  "maxRetries": 3
}

| Field | Default | Description | | --------------- | ------------------------------------------------------------ | ---------------------------------- | | notifierUrl | https://helm-studio-server.publicker.dev/webhooks/opencode | Full webhook endpoint URL | | serverId | — | Auto-generated on first run | | hmacSecret | — | Auto-generated on first run | | enabledEvents | All four events | Which events trigger notifications | | timeoutMs | 5000 | Request timeout in ms | | maxRetries | 3 | Max retry attempts |

Supported Events

| Event | Webhook Trigger | | ------------------ | ----------------------------------- | | session.idle | Session completed successfully | | session.error | Session encountered an error | | question.asked | Session has a question for the user | | permission.asked | Session needs user approval |

Only main session events trigger notifications — sub-agent sessions (Task, explore, general) are automatically filtered out.

Webhook Payload

Each webhook is a signed JSON POST to the configured notifierUrl:

POST /webhooks/opencode
Headers:
  Content-Type: application/json
  x-opencode-signature: <HMAC-SHA256 hex digest of body>
  x-opencode-server-id: <server UUID>

{
  "serverId": "uuid",
  "sessionId": "session-id",
  "event": "session.idle",
  "timestamp": 1712500000000,
  "summary": "Session completed successfully",
  "title": "Session title",
  "workspace": "/path/to/project",
  "projectName": "my-project",
  "metadata": { "status": "success" },
  "question": { "question": "Which option?", "options": ["A", "B"] },
  "permission": { "permissionTitle": "Write file", "permissionDescription": "src/index.ts" }
}

The question and permission fields are only present for their respective event types.

Security

• ~/.config/opencode-helm-studio-notifier/config.json contains your HMAC secret — do not commit it to version control
• Secrets are never logged (sensitive keys are redacted by the structured logger)
• All webhooks are signed with HMAC-SHA256
• The backend verifies signatures using timing-safe comparison

Development

bun install
bun run build      # type-check
bun run lint       # lint + format check (Biome)
bun run lint:fix   # auto-fix lint + format issues
bun test           # all tests
bun test:unit      # unit tests only
bun test:e2e       # e2e tests only