create-opencode-plugin

Creating OpenCode Plugins

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

Procedure Overview

Step	Action	Read
1	Verify SDK reference	Run extract script
2	Validate feasibility	This file
3	Design plugin	references/hooks.md, references/hook-patterns.md, references/CODING-TS.MD
4	Implement	references/tool-helper.md (if custom tools)
5	Add UI feedback	references/toast-notifications.md, references/ui-feedback.md (if needed)
6	Test	references/testing.md
7	Publish	references/publishing.md, references/update-notifications.md (if npm)

---

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

Scope	Path	Use Case
Project	.opencode/plugin/<name>/index.ts	Team-shared, repo-specific
Global	~/.config/opencode/plugin/<name>/index.ts	Personal, all projects

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

Parameter	Type	Description
project	Project	Current project info (id, worktree, name)
client	SDK Client	OpenCode API client
$	BunShell	Bun shell for commands
directory	string	Current working directory
worktree	string	Git worktree path

---

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

Mistake	Fix
Using client.registerTool()	Use tool: { name: tool({...}) }
Wrong event property names	Check references/events.md
Sync event handler	MUST use async
Not throwing to block	throw new Error() in tool.execute.before
Forgetting TypeScript types	import type { Plugin } from "@opencode-ai/plugin"

---

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:

Need	Use
Brief alerts, warnings	Toast
Detailed stats, multi-line	Inline message
Config validation errors	Toast
Session completion notice	Toast or inline

---

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

<reference_summary>

Reference Files Summary

File	Purpose	When to Read
hooks.md	Hook signatures (auto-generated)	Step 3-4
events.md	Event types (auto-generated)	Step 4 (if using events)
tool-helper.md	Zod tool schemas (auto-generated)	Step 4 (if custom tools)
hook-patterns.md	Hook implementation examples	Step 3-4
CODING-TS.MD	Code architecture principles	Step 3 (Design)
examples.md	Complete plugin examples	Step 4
toast-notifications.md	Toast popup API	Step 5 (if toasts needed)
ui-feedback.md	Inline message API	Step 5 (if inline needed)
testing.md	Testing procedure	Step 6
publishing.md	npm publishing	Step 7
update-notifications.md	Version toast pattern	Step 7 (for npm plugins)

</reference_summary>