You installed a plugin, omp told you it succeeded, and the tool never showed up. Or you upgraded and your memory config looks renamed, your keybindings changed, and semantic recall returns nothing. If you're running Oh My Pi (omp) — the ~12k-star terminal AI coding agent forked from Mario Zechner's pi, with hash-anchored edits, an optimized tool harness, LSP, Python, browser, and subagents — most of the pain clusters into three buckets: the Bun runtime version, plugin/extension compatibility inside the compiled binary, and post-upgrade migrations. Here's how to diagnose and fix each, with the real GitHub issues behind them.
Almost every "it installed but doesn't work" report traces back to one fact: omp ships as a Bun-compiled binary, and module resolution inside that binary's virtual filesystem (
/$bunfs/root) does not behave like a normalnode_moduleslookup.
Start with the Bun version
Oh My Pi requires Bun >= 1.3.14. The recommended install is:
bun install -g @oh-my-pi/pi-coding-agent
Supported platforms are macOS (Intel and ARM64), Linux (x64 and ARM64), and Windows. If you're below 1.3.14, several plugin and binary-resolution behaviors won't work as documented, so upgrade Bun before chasing anything else.
If you didn't install via Bun, the other documented methods are:
| Method | Command |
|---|---|
| Shell installer (macOS/Linux) | curl -fsSL https://omp.sh/install | sh |
| Homebrew | brew install can1357/tap/omp |
| Windows PowerShell | irm https://omp.sh/install.ps1 | iex |
| Version pinning (mise) | mise use -g github:can1357/oh-my-pi |
One note before you dig in: these troubleshooting steps assume the canonical can1357/oh-my-pi build. There's at least one third-party fork (az9713/oh-my-pi with agent harness enhancements), and behavior may differ there.
Plugin and extension compatibility
This is where most of the frustration lives. The symptom is almost always the same — install succeeds, capability never appears — but there are a few distinct root causes.
"Cannot find module @oh-my-pi/pi-ai from /$bunfs/root"
This is issue #1215 (closed). Installing the plugin pi-schedule-prompt@0.3.0 via omp plugin install failed on OMP 15.1.7 (macOS arm64). The legacy-pi-compat shim remaps @mariozechner/pi-ai to @oh-my-pi/pi-ai, but Bun.resolveSync() then searches from inside the compiled binary's virtual filesystem (/$bunfs/root), where there's no usable parent node_modules. The plugin silently drops.
The documented fix is to rewrite the plugin as a native OMP extension (~200 lines) using only pi.zod, pi.registerTool, and pi.sendUserMessage — avoiding any ES imports from @mariozechner/* or @oh-my-pi/*. If you control the plugin, that's the durable path. If you don't, file or follow the upstream issue for that plugin.
"Cannot find module /$bunfs/root/packages/utils/src/index.js" and a missing /swarm
This is issue #2168 (closed, fixed by PR #2171). On the OMP 15.10.8 release binary (macOS arm64), extensions importing @oh-my-pi/pi-* failed with a missing bundled-path error. The cause: the legacy-pi-compat package-root override returned a non-existent bundled path without throwing, so the catch-and-fallback logic never fired. This was bad enough to break the first-party @oh-my-pi/swarm-extension, meaning the /swarm command never registered.
If /swarm (or another first-party extension) is missing on an older 15.10.x build, upgrade — the fix shipped in a release after 15.10.8.
Installs that report success but silently fail to load
Issue #2312 (open, labeled bug/p2) captures the general pattern: "OMP npm plugin install can succeed while extension load silently fails from unresolved peer/nested deps." A related PR #2313 exists. The takeaway is to never trust the install message alone — confirm the extension actually registered (its command or tool shows up) before assuming it works.
Claude Code plugin skills not appearing in autocomplete
Issue #2415 (closed, fixed by PR #2417). Claude Code plugin skills such as /understand, installed via the omp plugin manager, were invisible in autocomplete and couldn't be invoked. The skill discovery code didn't scan the plugin cache directory ~/.omp/plugins/cache/plugins/*/skills/. If your installed skills vanished, upgrade to a build with the fix.
pi / pi-mono extensions don't install at all
Issue #433 (closed): pi-mono plugins use a similar extension interface but can't be installed via omp plugin install because of a manifest schema mismatch — they lack the key "pi/omp": { extensions: [] } that the installer expects. The same issue noted that disabledExtensions config didn't connect to the actual capability system. The broader compatibility theme is tracked in issue #2166. Bottom line: a plugin that works under upstream pi is not guaranteed to load under omp.
Post-upgrade confusion: memory and keybindings
The second-biggest support category is "it changed after I updated." These are mostly automatic migrations, not breakage — but they surprise people.
mnemosyne became mnemopi
Around release v15.7.3, the local SQLite memory backend identifier was renamed from mnemosyne to mnemopi (the Bun/TypeScript port of the Mnemosyne engine). Existing configs migrate automatically on load:
memory.backend: mnemosynebecomesmemory.backend: mnemopi- the
mnemosynesettings block is renamed tomnemopi
Nothing is lost; the keys just changed names. For reference, memory is off by default — you enable it with:
memory:
backend: local
A legacy memories.enabled: true auto-migrates to memory.backend: local when no explicit backend is set. Other relevant keys include memories.maxRolloutAgeDays (30), memories.minRolloutIdleHours (12), and memories.summaryInjectionTokenLimit (5000).
"Memory feels reset" — consolidation timing changed
If older sessions never seemed to remember anything, this is why: as of roughly v15.11.3 / v15.12.0, mnemopi consolidation now runs automatically on session shutdown. Previously, sessions without an explicit /memory enqueue never consolidated facts at all. To manage memory directly:
| Command | Effect |
|---|---|
/memory clear or /memory reset | Delete the active backend's memory data/artifacts |
/memory enqueue or /memory rebuild | Force consolidation |
"memory_embeddings = 0 rows" — semantic recall silently fails
Issue #2322 (open, opened June 11 2026): mnemopi semantic/vector recall silently fails. Users see memory_embeddings = 0 rows in the DB despite retention attempts, with no log explanation. The root cause is three bare catch {} blocks in the embedding pipeline (runEmbedding, getLocalModel, and the embed local-model path) swallowing errors, plus the mnemopi.debug: true flag not propagating into the core pi-mnemopi library.
Compounding this: in v15.12.0 (June 12 2026), local embeddings (fastembed and onnxruntime-node) were moved from bundled dependencies to optional peer dependencies that install on demand (to a runtime cache under ~/.omp/). So after upgrading, local-embedding memory may need an extra on-demand download and can look non-functional until it finishes installing. Give it time, watch for the runtime download, and track #2322 for the error-surfacing fix.
Keybindings moved, and double-Esc shifted
Keybindings config migrated to ~/.omp/agent/keybindings.yml, with automatic migration from the legacy keybindings.json (keybindings.yaml is still supported). If a shortcut feels different post-upgrade: double-Esc was remapped to /tree at one point and then restored to the message-history selector in v15.12.1. If yours is wrong, check the migrated YAML file.
For context on currency, the latest releases at time of writing are v15.12.4 (June 13) and v15.12.0 (June 12, which added /collab encrypted session sharing, spectator mode, and HTML session exports).
How to update safely
The exact self-update mechanism isn't confirmed in the docs — there may or may not be a dedicated omp upgrade command, so don't rely on one you can't verify. The safe path is to re-run the install method you originally used: the Bun global install, the omp.sh shell installer, Homebrew, or mise. Match your install method to your upgrade method and you avoid the messiest failure modes.
Bottom line
Three rules cover most Oh My Pi trouble. First, get Bun to >= 1.3.14 before anything else. Second, treat "install succeeded" as unverified — the compiled binary's /$bunfs/root resolution breaks plugins that import @mariozechner/* or @oh-my-pi/* (#1215, #2168), npm installs can silently fail to load (#2312), and skills can hide if discovery misses the cache dir (#2415); when in doubt, prefer native extensions and upgrade past the fixes. Third, after an upgrade, expect automatic migrations — mnemosyne to mnemopi, consolidation now on shutdown, embeddings as on-demand peer deps (#2322), and relocated keybindings — and reach for /memory enqueue and /memory rebuild rather than assuming memory is broken. This tooling moves fast, so verify version-specific details against the current release notes before acting.