sandgardenhq/opencode-plugin-development

OpenCode Plugin Development

Overview

Plugins allow you to extend OpenCode by hooking into various events, adding custom tools, and customizing behavior. This skill guides you through creating plugins using JavaScript/TypeScript modules that export plugin functions.

When to Use

• Adding new features or integrations
• Modifying OpenCode's default behavior
• Implementing custom tools
• Handling specific events (e.g., notifications)
• Protecting sensitive files

Plugin Structure

Basic Plugin Format

A plugin is a JavaScript/TypeScript module that exports one or more plugin functions. Each function receives a context object and returns a hooks object.

export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")
  return {
    // Hook implementations go here
  }
}

Context Parameters

• project: Current project information
• directory: Current working directory
• worktree: Git worktree path
• client: OpenCode SDK client for AI interactions
• $: Bun's shell API for executing commands

TypeScript Support

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

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hook implementations
  }
}

Plugin Location

Plugins are loaded from:

1. .sgai/plugin directory in your project
2. Or globally in ~/.config/opencode/plugin

Available Hooks

Event Hook

Listen for OpenCode events:

return {
  event: async ({ event }) => {
    if (event.type === "session.idle") {
      await $`osascript -e 'display notification "Session completed!" with title "opencode"'`
    }
  }
}

Tool Hook

Add custom tools:

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

export const CustomToolsPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      mytool: tool({
        description: "This is a custom tool",
        args: {
          foo: tool.schema.string(),
        },
        async execute(args, ctx) {
          return `Hello ${args.foo}!`
        },
      }),
    },
  }
}

Tool Execution Hooks

Intercept tool execution:

return {
  "tool.execute.before": async (input, output) => {
    if (input.tool === "read" && output.args.filePath.includes(".env")) {
      throw new Error("Do not read .env files")
    }
  }
}

Development Process

1. Plan the Plugin: Determine what functionality to add and which hooks to use
2. Create Plugin File: Write the plugin module in .sgai/plugin/
3. Implement Hooks: Add the necessary hook functions
4. Test Plugin: Load and test in OpenCode
5. Handle Errors: Add proper error handling and logging

Best Practices

• Use TypeScript for better development experience
• Handle errors gracefully in hooks
• Test plugins thoroughly before deployment
• Document custom tools clearly
• Follow OpenCode's plugin conventions

Common Patterns

Notification Plugin

Send notifications on events:

export const NotificationPlugin = async ({ $ }) => {
  return {
    event: async ({ event }) => {
      if (event.type === "session.idle") {
        await $`notify-send "OpenCode" "Session completed"`
      }
    }
  }
}

File Protection Plugin

Prevent access to sensitive files:

export const FileProtection = async () => {
  return {
    "tool.execute.before": async (input) => {
      const protectedPatterns = [/\.env$/, /secrets\//, /private\//]
      if (input.tool === "read" && protectedPatterns.some(p => p.test(input.args.filePath))) {
        throw new Error("Access denied to protected file")
      }
    }
  }
}

Custom Tool Plugin

Add domain-specific tools:

export const DomainTools: Plugin = async () => {
  return {
    tool: {
      analyzeCode: tool({
        description: "Analyze code for specific patterns",
        args: {
          filePath: tool.schema.string(),
          pattern: tool.schema.string()
        },
        execute: async (args) => {
          // Implementation
          return "Analysis complete"
        }
      })
    }
  }
}

Troubleshooting

• Ensure plugin files are in the correct location
• Check console logs for initialization errors
• Verify hook signatures match the expected types
• Test custom tools with simple inputs first
• Use the OpenCode client for AI interactions when needed