Creating OpenCode Plugins

<critical> Re-read this file periodically during plugin development to refresh context and ensure you're following the correct procedure. </critical>

<workflow>

Procedure Overview

Step 1: Verify SDK Reference (REQUIRED)

Before creating any plugin, MUST regenerate the API reference to ensure accuracy:

bun run .opencode/skill/create-opencode-plugin/scripts/extract-plugin-api.ts

This generates:

• references/hooks.md - All available hooks and signatures
• references/events.md - All event types and properties
• references/tool-helper.md - Tool creation patterns

Step 2: Validate Feasibility (REQUIRED)

MUST determine if the user's concept is achievable with available hooks.

Feasible as plugins:

• Intercepting/blocking tool calls
• Reacting to events (file edits, session completion, etc.)
• Adding custom tools for the LLM
• Modifying LLM parameters (temperature, etc.)
• Custom auth flows for providers
• Customizing session compaction
• Displaying status messages (toasts, inline)

NOT feasible (inform user):

• Modifying TUI rendering or layout
• Adding new built-in tools (requires OC source)
• Changing core agent behavior/prompts
• Intercepting assistant responses mid-stream
• Adding new keybinds or commands
• Modifying internal file read/write
• Adding new permission types

If not feasible, MUST inform user clearly. Suggest:

• OC core changes: contribute to packages/opencode
• MCP tools: use MCP server configuration
• Simple automation: use shell scripts

Step 3: Design Plugin

READ: references/hooks.md for available hooks, references/hook-patterns.md for implementation patterns.

READ: references/CODING-TS.MD for code architecture principles. MUST follow these design guidelines:

• Modular structure: Split complex plugins into multiple focused files (types, utilities, hooks, tools)
• Single purpose: Each function does ONE thing well
• DRY: Extract common patterns into shared utilities immediately
• Small files: Keep individual files under 150 lines - split into smaller modules as needed
• No monoliths: MUST NOT put all plugin code in a single index.ts file

Plugin Locations

Basic Structure

import type { Plugin } from "@opencode-ai/plugin"

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  // Setup code runs once on load

  return {
    // Hook implementations - see references/hook-patterns.md
  }
}

Context Parameters

Step 4: Implement

READ: references/hook-patterns.md for hook implementation examples.

READ: references/tool-helper.md if adding custom tools (Zod schemas).

READ: references/events.md if using event hook (event types/properties).

READ: references/examples.md for complete plugin examples.

ALWAYS READ: references/CODING-TS.MD and follow modular design principles.

Plugin Structure (Non-Monolithic)

For complex plugins, MUST use a modular directory structure:

.opencode/plugin/my-plugin/
├── index.ts          # Entry point, exports Plugin
├── types.ts          # TypeScript types/interfaces
├── utils.ts          # Shared utilities
├── hooks/            # Hook implementations
│   ├── event.ts
│   └── tool-execute.ts
└── tools/            # Custom tool definitions
    └── my-tool.ts

Example modular index.ts:

import type { Plugin } from "@opencode-ai/plugin"
import { eventHooks } from "./hooks/event"
import { toolHooks } from "./hooks/tool-execute"
import { customTools } from "./tools"

export const MyPlugin: Plugin = async ({ project, client }) => {
  return {
    ...eventHooks({ client }),
    ...toolHooks({ client }),
    tool: customTools,
  }
}

Keep each file under 150 lines. Split as complexity grows.

Common Mistakes

Step 5: Add UI Feedback (Optional)

Only if plugin needs user-visible notifications:

READ: references/toast-notifications.md for transient alerts (brief popups)

READ: references/ui-feedback.md for persistent inline status messages

Choose based on:

Step 6: Test

READ: references/testing.md for full testing procedure.

Quick Test Steps

1. Create test folder with opencode.json:

``jsonc { "plugin": ["file:///path/to/your/plugin/index.ts"], } ``

1. Verify plugin loads:

``bash cd /path/to/test-folder opencode run hi ``

1. Test interactively:

``bash opencode ``

1. SHOULD recommend specific tests based on hook type used.

Step 7: Publish (Optional)

READ: references/publishing.md for npm publishing.

READ: references/update-notifications.md for version update toasts (for users with pinned versions).

</workflow>

<reference_summary>

Reference Files Summary

</reference_summary>