Plugin SDK
“Hooks Are the API”
A well-designed hook system makes the agent infinitely extensible.
The @opencode-ai/plugin package defines hooks as the public API between the agent core and extensions. Hooks cover every lifecycle stage: config loading, tool execution (before and after), message processing, permissions, authentication, shell environment setup, and session compaction. This comprehensive coverage means most extension needs are met without patching core code.
Architecture Flow
The Problem: Stable Core, Unstable Extensions
Every plugin system faces the same tension: the core must be stable enough to reason about, yet flexible enough to accommodate unknown future needs. OpenCode's plugin SDK resolves this by defining hooks as a TypeScript interface, a contract between core and extensions. The core declares: I will call these functions at these points. Plugins declare: I will provide functions matching these signatures. As long as both sides honor the interface, the core never needs to know about specific plugins, and plugins never need to patch the core.
Comprehensive Hook Coverage: Why Every Hook Exists
Each hook exists because someone needed it. The 'config' hook lets plugins modify settings before the agent starts. 'tool.execute.before' and 'tool.execute.after' enable logging, metrics, and validation. 'permission.ask' allows plugins to implement custom approval workflows. 'shell.env' injects environment variables for reproducible builds. 'experimental.session.compacting' lets plugins control how conversation history is summarized. This comprehensive coverage means the answer to 'can I do X with the plugin API?' is almost always 'yes, there is a hook for that.'
Design Decisions
The Hooks interface uses optional methods: a plugin implements only the hooks it needs. No base class to extend, no abstract methods to implement. This is structural typing in action.
The 'experimental.' prefix on certain hooks signals that their API may change. This gives the core team freedom to evolve while providing plugin authors early access. Once stabilized, the prefix is removed.
Comparison: Claude Code
The Plugin SDK is one of OpenCode's most distinctive features. Claude Code has no equivalent. The registerPlugin(plugin: Plugin) → hooks[] → lifecycle events pattern enables a marketplace-style ecosystem where third-party plugins add capabilities (new tools, permission policies, config transformations) without forking the core repository.
Deep Dive: Design Decisions
Hooks Are the Public API
The @opencode-ai/plugin package defines hooks (config, tool, permission, chat, event, etc.) that plugins implement. This is the contract between the agent core and the extension ecosystem — stable, versioned, and documented.
Cover Every Stage of the Agent Lifecycle
Hooks exist for config loading, tool execution (before/after), message processing (transform, params, headers), permissions, shell environment setup, and session compacting. Every extensibility point is covered.