@scrylog/opencode-plugin

@scrylog/opencode-plugin is an OpenCode plugin that sends session and permission events to the scrylog daemon webhook in real time.

This is the recommended OpenCode integration when scrylog is running in hooks mode.

When To Use This Plugin

Use this plugin when:

• you run OpenCode inside tmux
• you want scrylog to receive immediate session updates
• you want the best available correlation between OpenCode sessions and tmux panes
• you want hooks mode, which is the recommended OpenCode mode in scrylog

Do not use this plugin as your primary integration when:

• you are using opencode.mode: "sse"
• you want standalone-only OpenCode monitoring through opencode --port, opencode serve, or oc

In sse mode, the scrylog daemon accepts the HTTP request but ignores the payload and returns:

{ "ok": true, "skipped": "opencode-mode-sse" }

What The Plugin Does

The plugin listens for OpenCode session and permission events and forwards them to:

http://127.0.0.1:7788/api/webhook/opencode

If OpenCode is running inside tmux, the plugin also tries to write the current OpenCode session ID into the pane option:

@opencode-session

That gives scrylog an exact signal for correlating the OpenCode session with the tmux pane.

Requirements

• @scrylog/cli installed and reachable through the scrylog command
• scrylogd running
• OpenCode installed
• opencode.mode set to hooks in scrylog
• tmux installed if you want pane correlation

Installation

1. Install the plugin

bun install -g @scrylog/opencode-plugin

You can also use npm:

npm install -g @scrylog/opencode-plugin

2. Configure scrylog for hooks mode

Create or update ~/.config/scrylog/config.json:

{
  "opencode": {
    "mode": "hooks"
  }
}

You can also do this from the main operator CLI:

scrylog setup

Choose OpenCode, then choose hooks mode.

3. Enable the plugin in OpenCode

Register the plugin from the main operator CLI:

scrylog opencode hooks install

Or create or update ~/.config/opencode/opencode.json manually:

{
  "plugin": ["@scrylog/opencode-plugin"]
}

4. Start the daemon

scrylog daemon install
scrylog daemon start

Or run the daemon manually in the foreground:

scrylogd

5. Start OpenCode

Start OpenCode normally. The plugin loads automatically.

6. Verify it works

Open another terminal and check the daemon:

curl http://127.0.0.1:7788/api/sessions

You should see OpenCode sessions appear when they start receiving events.

You can also run:

scrylog doctor

That confirms local daemon reachability and current OpenCode mode.

Configuration

The plugin uses one environment variable:

| Variable | Default | Purpose | | --- | --- | --- | | SCRYLOG_URL | http://127.0.0.1:7788/api/webhook/opencode | Full webhook URL for the scrylog daemon |

Example: custom daemon port

SCRYLOG_URL=http://127.0.0.1:9000/api/webhook/opencode opencode

If you also moved the scrylog API port, make sure your scrylog config matches it:

{
  "api": {
    "tcpEnabled": true,
    "host": "127.0.0.1",
    "port": 9000
  }
}

Example: set it in your shell profile

export SCRYLOG_URL=http://127.0.0.1:9000/api/webhook/opencode

Supported Events

The plugin forwards these OpenCode events:

| Event | Meaning | | --- | --- | | session.created | New session created | | session.updated | Session metadata changed | | session.deleted | Session deleted | | session.status | State changed, such as busy, idle, or retry | | session.idle | Explicit idle signal | | session.error | Session error | | permission.updated | Permission prompt state updated | | permission.asked | Permission prompt shown | | permission.replied | Permission prompt answered |

Request Format

Each event is sent as:

• POST
• Content-Type: application/json

Example payload:

{
  "event": "session.status",
  "directory": "/Users/you/projects/my-app",
  "sessionID": "ses_123",
  "status": {
    "type": "busy"
  }
}

For session.created and session.updated, OpenCode may also include richer info payloads such as title, timestamps, and parentID.

Hooks Mode Vs SSE Mode

In hooks mode

The daemon uses plugin webhook events as the primary OpenCode signal.

What you get:

• immediate OpenCode state updates
• permission prompt visibility
• better tmux correlation when the pane option is available
• child and subagent visibility when OpenCode emits parent session IDs

In sse mode

The daemon ignores this plugin and instead connects to OpenCode over its HTTP server.

Use sse mode when you run:

• opencode --port 4096
• opencode serve
• oc

In sse mode:

• OpenCode is shown as standalone only
• OpenCode tmux panes are hidden in scrylog
• this plugin is optional and effectively inactive

Limitations

• The plugin can only provide exact tmux correlation when it can write @opencode-session in the active pane.
• OpenCode attach inside tmux still does not have complete exact-session support without an upstream OpenCode signal.
• If the daemon is down, webhook sends are fire-and-forget and are silently dropped.

Troubleshooting

The plugin is installed but OpenCode sessions do not appear

Check all of the following:

1. scrylogd is running
2. opencode.mode is hooks
3. OpenCode config includes "plugin": ["@scrylog/opencode-plugin"]
4. SCRYLOG_URL points to the correct daemon address
5. curl http://127.0.0.1:7788/api/health succeeds
6. scrylog doctor reports OpenCode mode: hooks

The daemon says webhook events were skipped

Your daemon is probably running with opencode.mode: "sse". Switch it to hooks if you want this plugin to drive OpenCode updates.

I want standalone-only OpenCode monitoring instead

Do not use this plugin as the primary integration. Set opencode.mode to sse in scrylog and start OpenCode with a reachable HTTP endpoint or use oc.

Related

• scrylog for the dashboard, daemon, API, MCP server, and oc
• Root documentation: README.md