Plugin API: api.command.* removed in v1.14.42 with no deprecation cycle, no changelog entry, no migration guide

[RobinVivant]

Description

opencode v1.14.42 silently removed the entire api.command namespace from the public TUI plugin API (api.command.register, api.command.trigger, api.command.show) in PR #26053 ("introduce opentui keymap as sole key/cmd engine"). The replacement is api.keymap.registerLayer({ commands, bindings }).

There was no deprecation cycle, no console warning, and no mention in the v1.14.42 or v1.14.43 release notes. Plugins that used the public API now crash on init with:

TypeError: undefined is not an object (evaluating 'api.command.register')

Because the crash happens during TUI plugin init, api.slots.register(...) never runs — so affected plugins not only lose their command palette entries, they also disappear entirely from the sidebar. To the user it looks like the plugin was uninstalled.

Not a duplicate of #26546. #26546 covers the cascading bootstrap crash introduced by the same PR (terminal goes blank on startup), and it was fixed in v1.14.43. This issue is about the underlying public-API removal — which is not fixed in v1.14.43: TUI plugins that call api.command.* still crash on 1.14.43 (just no longer crashing the whole TUI host). The bot pattern-matched on api.command; the surface area and the resolution are different.

Why this is a problem

A breaking change to a public, documented plugin API inside a patch-version bump is bad practice for any project — even one whose audience is plugin authors. Concretely:

1. Semver violation. 1.14.41 → 1.14.42 is a patch bump. Removing a public API (not even renaming it under the same shape) is unambiguously breaking.
2. No deprecation cycle. The new api.keymap.registerLayer could have been added in one release with api.command.* kept as a thin shim that delegated to the new code (and emitted a one-time console.warn naming the new API). Removal could have happened in a follow-up minor.
3. Missing changelog entry. v1.14.42 release notes mention "Scout agent", HTTP compression, footer mode, etc. — but nothing about the TUI plugin API surface change. v1.14.43 is the same.
4. No migration guide. The new api.keymap.registerLayer({ commands, bindings }) shape is documented in packages/opencode/specs/tui-plugins.md, but there is no "porting from api.command.register" note pointing existing plugin authors at it. Plugin authors find out by getting bug reports.
5. The bundled @opencode-ai/plugin types still declare the old surface for many users (~/.opencode/node_modules/@opencode-ai/plugin/dist/tui.d.ts is still 1.14.29 here). Plugin authors who type-check against those types get no compile-time signal that they should migrate. The runtime crash is the first they hear about it.

Suggested remediation

• Re-add api.command as a thin compat shim that calls into the new api.keymap registry under the hood (with a one-time console.warn naming api.keymap.registerLayer as the replacement). Mark it @deprecated in the type definitions.
• Document the migration in the next release notes, ideally in a dedicated "Plugin API" section.
• For future API removals: at least one minor-bump deprecation window where the old API still works but warns, then a clean removal in the next minor.
• Consider a small BREAKING_CHANGES.md for the plugin surface specifically — plugin authors don't read every release note, but they will read a file that exists for them.

Plugins

@cortexkit/opencode-magic-context@0.17.2, @cortexkit/aft-opencode@0.20.1, local concord plugin (all three call api.command.register(...) unconditionally with no fallback).

OpenCode version

1.14.42 (also confirmed broken on 1.14.43)

Steps to reproduce

1. bun add -g opencode-ai@1.14.43
2. Install any TUI plugin that calls api.command.register(...) — e.g. @cortexkit/aft-opencode@latest in ~/.config/opencode/tui.json plugin array.
3. Hard-restart opencode (pkill -f 'opencode-ai/bin/.opencode' from a separate terminal, then relaunch).
4. Plugin's sidebar pane is missing. Check ~/.local/share/opencode/log/*.log for the TypeError: undefined is not an object (evaluating 'api.command.register') entry.

Affected plugins observed on this machine:

Plugin	Source path	Failing call site
@cortexkit/opencode-magic-context@0.17.2	src/tui/index.tsx	line 468
@cortexkit/aft-opencode@0.20.1	src/tui/index.tsx	line 206
Local concord plugin (now patched)	tui/index.tsx	line 503

Stack trace excerpt (identical for all three):

ERROR service=tui.plugin path=@cortexkit/aft-opencode@latest id=aft-opencode
  error={"type":"TypeError","message":"undefined is not an object (evaluating 'api.command.register')",
  "stack":"...at tui (.../@cortexkit/aft-opencode/src/tui/index.tsx:188:7)..."}
  failed to initialize tui plugin

Screenshot and/or share link

N/A — see log excerpt above. Filed in parallel: cortexkit/aft#33 and a comment on cortexkit/magic-context#61.

Operating System

macOS 15.2 (Darwin 24.x, arm64)

Terminal

Ghostty

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• This issue does not use one of the required issue templates (Bug Report, Feature Request, or Question). Please re-submit using the appropriate template — this appears to be a Bug Report, so please use the Bug Report template and fill in the required fields.

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

---

This issue might be a duplicate of existing issues. Please check:

• [BUG on v1.14.42]: Upon trying to start up, non-descript error message is shown #26546: Covers the same v1.14.42 startup crash caused by the api.command removal — the root cause described in your issue is the same breaking change that triggered that regression.

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

Thanks for updating the issue! It now follows the contributing guidelines and includes all the required information. The needs:compliance label has been removed.

[RobinVivant]

@ opencode-agent — re-edited the body to match the Bug Report template (Description / Plugins / OpenCode version / Steps to reproduce / Operating System / Terminal sections).

On the duplicate flag for #26546 — they are different issues; the bot pattern-matched on api.command but the surface area and the resolution are different:

• [BUG on v1.14.42]: Upon trying to start up, non-descript error message is shown #26546 — [BUG on v1.14.42]: Upon trying to start up, non-descript error message is shown. Symptom: terminal goes blank, TUI never renders. This was fixed in v1.14.43 (rollback of the cascading bootstrap regression). The api.command API removal is mentioned only as a passing side-note by @capyBearista deep in the comments.
• Plugin API: api.command.* removed in v1.14.42 with no deprecation cycle, no changelog entry, no migration guide #26557 (this issue) — the public TUI plugin API surface api.command.{register,trigger,show} was removed in PR introduce opentui keymap as sole key/cmd engine #26053 with no deprecation cycle and no changelog mention. This was NOT fixed in v1.14.43: TUI plugins that call api.command.* still crash on 1.14.43, they just no longer crash the entire host. Three concrete plugins on my machine confirm the post-1.14.43 breakage (@cortexkit/opencode-magic-context@0.17.2, @cortexkit/aft-opencode@0.20.1, local concord plugin).

Happy to amend further if anything still trips the compliance check.

[kommander]

My bad. I have to say though that this is not true:

breaking change to a public, documented plugin API

we did not yet document the TUI API on purpose, because we are still exploring and dogfooding.

I'll add a backwards compat shim with deprecation notice.

[RobinVivant]

fair enough, thank you!

[kitlangton]

This should be addressed by #26564, which reintroduced the command API shim for compatibility.

Could you try v1.14.45 and confirm whether your affected plugins initialize again? If anything still fails, please share the new plugin init error from the log.