Repository navigation
Description
Description
First off β huge thanks for building OmO. It's an incredible piece of work that transforms how we use OpenCode. π
I ran into a black screen issue on Windows and spent some time digging into the root cause. Sharing my findings below in case it helps others, and to see if there's a path toward a proper fix.
Environment
| Component | Version |
|---|---|
| OS | Windows 11 (x64) |
| OpenCode | 1.4.6 (Go binary via npm) |
| oh-my-opencode | 3.17.4 |
| Bun | 1.3.12 |
| Node.js | v22.22.2 |
Symptoms
After installing OmO and registering the plugin in opencode.json, running opencode shows a completely black/blank TUI. The process hangs and becomes unresponsive. Removing the plugin from config restores normal startup.
Root Cause
The plugin bundle (dist/index.js) contains a Bun-specific import at line 147678:
// src/plugin/ultrawork-db-model-override.ts
import { Database } from "bun:sqlite";OpenCode's Go binary has an embedded JS runtime for loading plugins. This runtime does not support the bun: protocol. When the plugin is loaded synchronously at startup, this unresolved import blocks the main thread, preventing the TUI from rendering.
How I confirmed this
Using OpenCode's debug logging:
# With plugin β hangs after config loading, never reaches TUI initialization
opencode --print-logs --log-level DEBUG
# Pure mode (no plugins) β loads all TUI plugins normally
opencode --pure --print-logs --log-level DEBUGIn pure mode, logs show loading internal tui plugin entries immediately. With the plugin, the process stops at config loading and never reaches TUI plugin initialization.
Additionally, the models.dev fetch during plugin init times out in China (GFW), which adds to the startup delay β but the primary blocker is the bun:sqlite import.
Workaround
I was able to fix the black screen by replacing the bun:sqlite import with a safe stub:
node -e "
const fs = require('fs');
const home = process.env.HOME || process.env.USERPROFILE;
const targets = [
home + '/.cache/opencode/packages/oh-my-openagent@latest/node_modules/oh-my-openagent/dist/index.js',
home + '/.config/opencode/node_modules/oh-my-opencode/dist/index.js'
].filter(p => { try { return fs.existsSync(p); } catch { return false; } });
const old = 'import { Database } from \"bun:sqlite\";';
const stub = 'var Database = class { constructor() { return { prepare: () => ({ get: () => null, run: () => null, all: () => [] }) }; } };';
targets.forEach(path => {
let content = fs.readFileSync(path, 'utf-8');
if (content.includes(old)) {
content = content.replace(old, stub);
fs.writeFileSync(path, content, 'utf-8');
console.log('Patched: ' + path);
}
});
"After patching, OpenCode starts normally with full OmO functionality β Sisyphus agent, background agents, MCPs, ultrawork, etc. Only the ultrawork-db-model-override feature (model name override in session DB) is affected by the stub.
Limitation: The patch must be re-applied after every OmO update.
Suggested Fix
A few possible approaches, from simplest to most robust:
-
Conditional import β Wrap the
bun:sqliteimport in a try/catch or use dynamicimport()so the module degrades gracefully when Bun APIs are unavailable. -
Runtime detection β Check for
typeof Bun !== 'undefined'before using Bun-specific APIs, and fall back to a no-op or alternative SQLite library. -
Build-time target β If the bundle is built with Bun, consider producing a runtime-agnostic variant for environments that don't ship the Bun runtime.
I'm happy to submit a PR if any of these approaches sound reasonable.
Additional Context for Users in China
Users in mainland China face an additional layer of difficulty:
bunx oh-my-opencode installmay timeout due to npm registry accessopencode plugincommand also times out when downloading packagesmodels.devfetch during init is blocked by GFW
Workarounds: set npm config set registry https://registry.npmmirror.com/ before installation, and use OMO_SEND_ANONYMOUS_TELEMETRY=0 to skip analytics calls.
Related Issues
- [Bug]: OpenCode shows blank screen after installing oh-my-opencode plugin on macOSΒ #596 β Blank screen after installing
- [Bug]: v3.1.9 causes TUI freeze/blank screen - CRITICAL REGRESSIONΒ #1292 β v3.1.9 TUI freeze (CRITICAL)
- oh-my-opencode@latest causes opencode TUI to hang on blank screenΒ #1301 β
@latestcauses TUI hang - [Bug]: [email protected] causes opencode to freeze/hang at TUI startupΒ #3143 β v3.15.2 causes freeze/hang
- anomalyco/opencode#12192 β Black screen on Windows
Happy to provide any additional debugging info if needed. Thanks again for the great project! π
Activity
herjarsa commentedon May 7, 2026
Likely fixed by PR #3832 π
The TUI black screen is caused by the οΏ½un:sqlite import crashing Node.js's ESM loader at plugin load time. When the plugin fails to load, OpenCode doesn't show any agents and the TUI appears broken.
PR #3832 fixes this by hiding the οΏ½un: import from the static parser, allowing the plugin to load gracefully in embedded JS runtimes.
Please test once #3832 merges!
Ganzhe2028 commentedon May 7, 2026
Also hit this β same root cause, slightly different symptom.
Environment
@latestto cached 3.17.12Symptom
Plugin loaded in config/doctor but only
buildandplanagents were available β all OMO agents (Sisyphus, Oracle, Librarian, etc.) disappeared. No black screen, just silently reduced to native agents only.Root cause
Same
bun:sqliteimport in 3.17.12. OpenCode's embedded JS runtime rejected thebun:protocol at plugin load time, causing the plugin to fail silently. Since the plugin registered via the config hook never ran, the agent registry fell back to defaults.Fix
[email protected]inopencode.json(this version already avoids thebun:sqlitecrash for CLI/Bun runtime).zprofileto prefer/Users/mac/.opencode/bin/opencode(1.14.33) over Homebrew's olderopencode 1.1.8, which also caused plugin diagnostic instabilityVerification
Pinning the version is more stable than floating
@latestsince the cached version can lag behind the fix. PR #3832 looks like the proper long-term fix β thenew Function()wrapper avoids the static ESM parse issue entirely. Thanks for the detailed analysis on this issue!fix(agents): copy factory mode to agent config for Desktop 1.14.x compat
code-yeongyu commentedon May 13, 2026
[sisyphus-bot] Closing this β fixed and shipped in v4.1.0 (also in v4.0.0+ for the specific
bun:sqliteimport).Thanks for the deep-dive analysis, @HP26666 β pinpointing line 147678 of
dist/index.js, identifying that the embedded JS runtime can't resolve thebun:protocol, and even providing a working stub patch. That's a textbook bug report πWhat landed: PR #3832 (
fix(desktop): hide bun:sqlite import from Node.js/Electron ESM loader) β thebun:sqliteimport is now wrapped innew Function("return import('bun:sqlite')")so the specifier is hidden from the static ESM parser at parse/load time and only evaluated at runtime whenglobalThis.Bunis defined. Embedded JS runtimes (OpenCode Desktop Electron AND the Go-binary's embedded runtime) can now load the plugin without hitting the unresolvablebun:protocol.PR #3964 (in v4.1.0) further shims 19 other
Bun.*call sites for full Electron/Node compatibility.@herjarsa already flagged that PR #3832 was the right fix here β confirmed.
If you still see the TUI black screen on v4.1.0+ on OpenCode 1.4.6 or newer, please reopen with
opencode --print-logs --log-level DEBUGoutput. Thanks π