Creating OpenCode Plugins

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:

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

2. Verify plugin loads:

   cd /​path/​to/​test-folder
   opencode run hi
   

3. Test interactively:

   opencode
   

4. 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>