Pi extensions/packages compatibility

[krikchaip]

Question

After trying to use OMP and passing the -e flag followed by the extension name from Pi, it seems like it's not working. I've tried both the -e flag and the omp install command followed by the extension name, using both NPM and other methods.

It seems like it can be installed and shows up in /plugins, but it's not working. I'm not sure if I need to enable any flags in the configuration to make Pi extensions compatible with OMP.

In the case of using the OMP -e flag followed by the extension, it doesn't seem to work at all. It doesn't load the extension and treats the -e flag as if it doesn't exist. Is there a way to make it work or make it compatible with Pi extensions?

Context

No response

Topic

Extensions

Platform

macOS

[roboomp]

Short version: both entry points work for Pi extensions, but they expect different inputs and each fails silently in the way you described.

omp -e <…> / --extension <…> — file path, not package name

-e is parsed as a configured extension path and joined against the current cwd before loading (src/cli/args.ts + src/extensibility/extensions/loader.ts#discoverAndLoadExtensions). Pass a path to a .ts/.js file, or a directory containing one of:

• a package.json whose omp.extensions (or legacy pi.extensions) lists entry files
• an index.ts / index.js

Examples:

omp -e ./.omp/extensions/my-ext.ts
omp -e ~/dev/my-pi-extension       # directory with package.json/index.ts

Passing a bare package name (omp -e my-extension) resolves to ./my-extension, which doesn't exist, and the failure is recorded via logger.error("Failed to load extension", …) in sdk.ts#loadSessionExtensions. That logger writes to ~/.omp/logs/omp.<YYYY-MM-DD>.log rather than the TUI, which is why it looks like -e "does nothing". Tail that file when you suspect a load error:

tail -F ~/.omp/logs/omp.$(date +%F).log

omp install <pkg> — needs an omp or pi manifest

omp install is a thin wrapper over omp plugin install / omp plugin link (src/commands/install.ts). It runs bun install <pkg> inside ~/.omp/plugins and records the entry in ~/.omp/plugins/omp-plugins.lock.json. That's why the package "shows up in /plugins" but does nothing at runtime: getEnabledPlugins in src/extensibility/plugins/loader.ts skips any package whose package.json has no omp or pi manifest block, and resolvePluginExtensionPaths only resolves entries declared in manifest.extensions.

So a Pi-ecosystem package will load only when its published package.json looks like:

{
  "name": "some-pi-extension",
  "pi": {
    "extensions": ["./index.ts"]
  }
}

(omp.extensions is preferred; pi.extensions is still honored for backwards compat — see getEnabledPlugins and docs/plugin-manager-installer-plumbing.md.) If the package you installed publishes its entry under some other key (e.g. only a top-level "main", or a non-standard "extensions" at the root), the plugin loader has nothing to resolve and the install is effectively inert.

Quick check:

cat ~/.omp/plugins/node_modules/<pkg-name>/package.json | jq '.omp // .pi'

If that's null, the package isn't declaring itself as an omp/Pi plugin and you'd have to use -e against its entry file directly, or open an issue against the upstream extension asking them to ship the manifest.

Pi → omp import remapping is automatic

For Pi extensions that are loaded (either path), the legacy-pi compat layer (src/extensibility/plugins/legacy-pi-compat.ts) rewrites @mariozechner/pi-*, @earendil-works/pi-*, and @oh-my-pi/pi-* imports to the host-bundled packages, plus the @sinclair/typebox → Zod shim. No flag needed; it's installed for every extension load. If a specific Pi extension still errors, the log line above will name the failing import and that's the right thing to paste here for follow-up.

---

If this didn't solve your issue, react 👎 on this comment and I'll keep it open.
Otherwise I'll auto-close in 4 hours.

[krikchaip]

let's say i want to try this plugin https://github.com/Whamp/pi-token-burden. what are the required steps

[krikchaip]

Is that -e only for local extensions? In Pi, it can target NPM or GitHub, but can't omp do that?

[roboomp]

For Whamp/pi-token-burden, the OMP-side steps are:

# npm package path; do not use Pi's `npm:` prefix here
omp install pi-token-burden

# start/restart omp after install, then in the session:
/token-burden

Or from GitHub:

omp install github:Whamp/pi-token-burden
# then restart/start omp and run:
/token-burden

Why those are the right commands:

• Its published package.json has:

"pi": {
  "extensions": ["./src/index.ts"]
}

OMP’s plugin loader accepts legacy pi.extensions, so omp install pi-token-burden should place it under ~/.omp/plugins/node_modules/pi-token-burden and discover ./src/index.ts automatically. You should not need -e for the installed package.

For a local clone/dev checkout instead:

git clone https://github.com/Whamp/pi-token-burden.git
cd pi-token-burden
pnpm install        # this plugin’s repo uses pnpm
omp -e ./src/index.ts
# then run /token-burden inside that OMP session

Important caveat: I checked the plugin source, and it statically imports this from Pi:

import { discoverAndLoadExtensions, SettingsManager } from "@mariozechner/pi-coding-agent";

OMP’s legacy Pi compat layer remaps @mariozechner/pi-coding-agent to OMP’s bundled @oh-my-pi/pi-coding-agent, but OMP currently does not export a SettingsManager symbol. So this particular plugin may install and be discovered, then fail during module import before /token-burden is registered.

If that happens, the confirmation will be in:

~/.omp/logs/omp.$(date +%F).log

Look for Failed to load extension and an error like Export named 'SettingsManager' not found. If you see that, the install steps are correct; the remaining issue is a Pi API compatibility gap for this specific plugin, not a missing flag.

---

If this didn't solve your issue, react 👎 on this comment and I'll keep it open.
Otherwise I'll auto-close in 4 hours.

[roboomp]

Yes — in current OMP, -e / --extension is only a direct filesystem extension path/directory loader.

It does not currently implement Pi’s one-shot remote forms like:

pi -e npm:pi-token-burden
pi -e git:github.com/Whamp/pi-token-burden

OMP splits those concerns:

# remote/package install path
omp install pi-token-burden
omp install github:Whamp/pi-token-burden

# direct local/path load path
omp -e ./src/index.ts
omp -e ./some-extension-dir

So for a remote package, install it first, restart/start OMP, then use the command it registers. For pi-token-burden, that should be /token-burden if the package loads successfully.

The compatibility layer is about loading Pi-style packages/manifests/imports once OMP has a local module to import; it does not make -e fetch npm/GitHub targets today. Adding Pi-style -e npm:… / -e git:… as a one-session remote loader would be an enhancement request rather than a flag/config setting that already exists.

---

If this didn't solve your issue, react 👎 on this comment and I'll keep it open.
Otherwise I'll auto-close in 4 hours.

[krikchaip]

{"timestamp":"2026-06-09T12:21:22.081+07:00","level":"error","pid":73728,"message":"Failed to load extension","path":"/Users/asol/.omp/plugins/node_modules/pi-token-burden/src/index.ts","error":"Failed to load extension: ResolveMessage: Cannot find module '/$bunfs/root/packages/coding-agent/src/extensibility/legacy-pi-coding-agent-shim.js' from '/Users/asol/.omp/plugins/node_modules/pi-token-burden/src/index.ts'"}

[krikchaip]

^ the log

[comicchang]

Still reproduces on v16.1.15 (macOS arm64, Homebrew binary).

Environment

• OMP: omp/16.1.15 — Mach-O compiled binary via Homebrew (local/omp/omp tap)
• Platform: macOS (darwin) arm64
• Bun: 1.3.14
• Plugins installed via bun add in ~/.omp/plugins/

Affected plugins

All third-party Pi community plugins fail to load:

• pi-dynamic-workflows, pi-lens, pi-powerline-footer, pi-subagents, pi-interactive-subagents, pi-web-access, pi-context-prune
• @ifi/pi-background-tasks, @ifi/pi-diagnostics, @ifi/pi-plan

Error

Failed to load extension: ResolveMessage: Cannot find module '@oh-my-pi/pi-coding-agent' from '.../pi-dynamic-workflows/src/agent.ts'

Also seen:

Cannot find module '//root/packages/coding-agent/src/extensibility/typebox.js'

Verified

1. @oh-my-pi/pi-coding-agent exists in ~/.omp/plugins/node_modules/ (v16.1.16)
2. Standalone bun resolves the package fine from the same directory
3. Changing imports to @oh-my-pi/* (via sed patch + postinstall hook) — same failure
4. Installing @oh-my-pi/pi-coding-agent as a direct dependency — same failure
5. strings /opt/homebrew/bin/omp confirms bunfs path references exist (typebox.js, legacy-pi-*-shim.js)
6. __validateLegacyPiPackageRootOverrides code present in binary
7. v16.1.15 release notes include fix(legacy-pi-compat): validated package-root override targets before rewrite #2171 and fix(coding-agent): avoid mixed-runtime self imports in loaders #2297

Additional context

The binary references bunfs entries but the modules cannot be loaded via file:// URLs. The Bun.resolveSync fallback from bunfs context also fails. This appears to be a macOS arm64 + compiled binary specific issue where bunfs entries are referenced but not accessible at runtime.

Related: #2168, #2171, #2297, #2778

[roboomp]

@comicchang This looks like a real loader regression, separate from @krikchaip's original question. Tracking it here is going to mix two unrelated threads — please open a dedicated bug so it gets routed and prioritized correctly. A couple of things will make that issue actionable on the first pass:

What the trace tells us so far

The second error you pasted is the smoking gun:

Cannot find module '//root/packages/coding-agent/src/extensibility/typebox.js'

That path is supposed to be /$bunfs/root/packages/coding-agent/src/extensibility/typebox.js. The $bunfs/ segment is missing, which means BUNFS_PACKAGE_ROOT was computed from an import.meta.dir value the current code doesn't handle. The computation lives here:

• packages/coding-agent/src/extensibility/plugins/legacy-pi-compat.ts — __computeBunfsPackageRoot(import.meta.dir) on line 95, called on line 104.

The existing regression tests (packages/coding-agent/test/extensibility/legacy-pi-bunfs-root.test.ts) only assert the two shapes Bun was known to report: POSIX /$bunfs/root and Win32 B:\~BUN\root. Something on Homebrew arm64 + Bun 1.3.14 is reporting a third form that __computeBunfsPackageRoot falls through with a stripped prefix, and bunfsPath then composes the broken //root/… path you see.

(For the record, __validateLegacyPiPackageRootOverrides is not in this codebase — you may be thinking of __computeBunfsPackageRoot.)

The diagnostic that unblocks the fix

Running this one-liner against your omp and pasting the output is what we need:

omp shell -- bun -e 'console.log(JSON.stringify({ metaDir: import.meta.dir, metaUrl: import.meta.url, isCompiled: typeof Bun !== "undefined" }))'

If omp shell is unavailable in 16.1.15, the equivalent log line from a failing extension load also pins it down — drop this snippet into any throwaway .ts and load it via omp -e ./debug.ts:

export default function (pi) {
  console.error("META_DIR:", import.meta.dir);
  console.error("META_URL:", import.meta.url);
}

That META_DIR value is exactly what __computeBunfsPackageRoot is fed at runtime in your binary. With it, the fix is a one-line case in that function plus a regression test alongside the existing ones.

Other things worth including in the new bug

• Output of ~/.omp/logs/omp.$(date +%F).log filtered for Failed to load extension and any legacy-pi lines.
• The exact omp -v and bun -v you have (you already gave these — repeat them in the new issue body so it's self-contained).
• Whether the same binary fails on a non-Homebrew install (e.g. curl … | bash script or npm i -g). That narrows it from "Mach-O arm64 in general" to "Homebrew's specific build flags" — both are plausible given the cross-references to fix(legacy-pi-compat): validated package-root override targets before rewrite #2171/fix(coding-agent): avoid mixed-runtime self imports in loaders #2297.
• Whether OMP_DEBUG=1 omp … (if your build honors it) prints the resolved BUNFS_PACKAGE_ROOT anywhere.

The other failure mode you cited —

Cannot find module '@oh-my-pi/pi-coding-agent' from '.../pi-dynamic-workflows/src/agent.ts'

— is a downstream symptom of the same BUNFS_PACKAGE_ROOT being broken: the onResolve hook tries the bunfs path first, that path is malformed, the fallback in resolveLegacyPiSpecifier then tries Bun.resolveSync(remappedSpecifier, importerDir), and that fails because the plugin only declared @mariozechner/pi-* peer deps (no @oh-my-pi/* to resolve against). Fixing the root computation should fix both traces.

If you'd rather not file separately, ping back with that META_DIR and we can keep the discussion here, but a fresh issue with the bug template is the path of least friction.

---

If this didn't solve your issue, react 👎 on this comment and I'll keep it open.
Otherwise I'll auto-close in 4 hours.