create-opencode-plugin

You SHOULD re-read this file periodically during plugin development to refresh context and ensure correct procedure. </overview>

Procedure Overview

Step 1: Verify SDK Reference (REQUIRED)

Before creating any plugin, you 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)

You 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, you 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

You MUST read references/hooks.md for available hooks and references/hook-patterns.md for implementation patterns.

You MUST read references/CODING-TS.MD for code architecture principles and 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: You 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

You MUST read:

• •references/hook-patterns.md for hook implementation examples
• •references/tool-helper.md if adding custom tools (Zod schemas)
• •references/events.md if using event hook (event types/properties)
• •references/examples.md for complete plugin examples
• •references/CODING-TS.MD and follow modular design principles

Plugin Structure (Non-Monolithic)

For complex plugins, you 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"],
   }
   

2. •

   Verify plugin loads:

   bash

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

3. •

   Test interactively:

   bash

   opencode
   

4. •

   You 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).

Reference Files Summary