Plugins System
Relevant source files
The following files were used as context for generating this wiki page:
The Plugins System in OpenWork serves as the primary extensibility mechanism for OpenCode, allowing the injection of custom tools and capabilities into agentic workflows. Plugins are essentially "capability packaging" that provide safer, scoped alternatives to raw CLI access while remaining more flexible than basic MCP integrations. The system is designed to be local-first, utilizing filesystem-based configuration files to manage plugin lifecycle and execution scope.
Sources: ARCHITECTURE.md:14-17, PRINCIPLES.md:14-15
Architectural Overview
The plugin architecture operates across two primary scopes: Project and Global. In Project scope, plugins are defined within the local workspace's opencode.json (or opencode.jsonc) file. Global scope plugins are managed via a centralized configuration file located in the user's home directory (e.g., ~/.config/opencode/opencode.json). The system supports both npm-packaged plugins and local filesystem-based plugins using the file:// protocol.
Sources: packages/server/src/plugins.ts:38-51, README.md:154-158
Plugin Scopes and Resolution
The following diagram illustrates how plugins are resolved and loaded by the system.
Sources: packages/server/src/plugins.ts:53-69
Core Components
1. Configuration Management
Plugins are primarily defined in a JSON array within the OpenCode configuration. The system uses jsonc-parser to handle updates, ensuring that comments and formatting in opencode.json are preserved during programmatic modifications.
| Property | Type | Description |
|---|---|---|
plugin | string[] | An array of plugin specifiers (package names or file paths). |
$schema | string | The OpenCode config schema URL. |
Sources: packages/app/src/app/context/extensions.ts:354-368, README.md:162-167
2. Plugin Specifiers
The system recognizes multiple types of plugin specifiers, which are normalized before processing:
- npm packages: e.g.,
opencode-wakatime - Local files: e.g.,
file:///path/to/plugin.js - Remote URIs:
http://,https://, orgit://protocols
Sources: packages/server/src/plugins.ts:9-21
API and Data Flow
OpenWork manages plugins through its internal SDK and server endpoints. While local "Host" mode can directly manipulate opencode.json, remote "Client" mode relies on the /config and /plugins API endpoints for listing and adding plugins.
Plugin Discovery Flow
The following sequence shows how the UI retrieves the active plugin list.
API Endpoints
| Method | Endpoint | Description | Auth |
|---|---|---|---|
GET | /workspace/:id/plugins | Lists all configured and discovered plugins. | Client |
POST | /workspace/:id/plugins | Adds a new plugin specifier to the project config. | Client |
DELETE | /workspace/:id/plugins/:name | Removes a plugin from the project config. | Client |
POST | /workspace/:id/engine/reload | Forces the OpenCode engine to re-read config. | Client |
Sources: packages/server/src/server.ts:380-435, packages/app/pr/plugin-endpoints.md:27-42
Installation and Guided Setup
OpenWork provides a "Suggested Plugins" interface that allows for both simple and guided installations. Guided installations include multi-step instructions, shell commands, and URL redirects to help users configure complex plugins (e.g., opencode-browser).
Guided Installation Logic
// From packages/app/src/app/pages/plugins.tsx
// Logic for rendering guided setup steps
<For each={plugin.steps ?? []}>
{(step, idx) => (
<div class="space-y-1">
<div class="text-xs font-medium text-gray-11">{idx() + 1}. {step.title}</div>
<Show when={step.command}>
<div class="text-xs font-mono bg-gray-2/60 border rounded px-3 py-2">
{step.command}
</div>
</Show>
</div>
)}
</For>
Sources: packages/app/src/app/pages/plugins.tsx:112-140, packages/app/src/app/constants.ts:16-52
Plugin State and Synchronization
OpenWork treats the configuration file as the source of truth for "installed" plugins. When a plugin is added or removed, the application marks a "reload required" state. This notifies the user that the OpenCode engine must be restarted or re-disposed to apply the changes, as the server disposes instances upon configuration updates.
Sources: packages/app/pr/plugin-endpoints.md:50-57, packages/app/src/app/context/extensions.ts:370-385
The Plugins System provides a robust framework for extending OpenCode capabilities while maintaining a local-first, configuration-driven approach. By supporting both project-specific and global plugins, it allows users to tailor their agentic workflows to specific workspaces or maintain a persistent toolset across their entire system.