anomalyco / anomalyco/opencode

[FEATURE]: Expose a durable TUI-ready event for server plugins to surface startup error

Open
#38,527 0 comments 0 reactions 1 assignee View on GitHub

@nexxeln is already working on this.

Since Jul 23, 2026.

Dominant language
TypeScript
Stars
209k
Forks
27.5k
PR merge metrics
PR metrics pending

Description

Feature hasn't been suggested before.
  • I have verified this feature I'm about to request hasn't been suggested before.
Describe the enhancement you want to request

Problem

Server plugins run during OpenCode instance bootstrap, before the terminal TUI has rendered and subscribed to tui.toast.show.
A server plugin can call:

await client.tui.showToast({
  query: { directory },
  body: {
    message: "Plugin startup failed",
    variant: "error",
  },
})

However, the event is non-durable. If the TUI has not subscribed yet, the toast is lost without feedback.
This leaves plugin authors with no supported way to surface startup/configuration failures before the user creates a session. Logs are the only reliable fallback.
Example
The some plugin fetches available models at startup. Failures can include:

  • missing auth token
  • timeout calling /v1/models
  • invalid API response
  • HTTP errors

The plugin can fall back safely, but the user cannot see why some models are unavailable.

Proposed API

Expose an event or lifecycle hook that runs after the TUI is ready to receive UI messages, but before a session is required.
Possible server-plugin hook:

"tui.ready"?: (input: { directory: string }) => Promise<void>
Or expose a durable toast API:
await client.tui.showToast({
  query: { directory },
  body: {
    message: "Some models could not be loaded: request timed out",
    variant: "error",
    duration: 8000,
    durable: true,
  },
})

A durable toast should be replayed once when a matching TUI instance subscribes, then removed.
Expected behavior

  1. Server plugin config hook detects a startup failure.
  2. Plugin records a startup notification.
  3. OpenCode renders that notification once the terminal TUI is initialized.
  4. No session creation should be required.
Why this matters

Plugins currently need to rely on logs, delay reporting until session.created, or misuse unrelated surfaces such as MCP status errors. A supported startup notification lifecycle would make plugin failures visible and actionable without workarounds.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.