Pet Plugin Template

A minimal template for creating OpenCode plugins. Copy this folder and customize it to build your own plugin.

Quick Start

1. Copy This Template

# From pets directory
cp -r _TEMPLATE_ my-plugin
cd my-plugin

2. Customize

Edit these files:

package.json:

• Change name to openpets/my-plugin
• Update description
• Add your environment variables in envVariables
• Add example queries in queries

index.ts:

• Rename TemplatePlugin to MyPlugin
• Add your tools to the tools array
• Implement your logic in the execute functions

opencode.json:

• Update if needed (usually no changes required)

3. Test

npm install
npm run quickstart

Basic Structure

export const MyPlugin = async () => {
  const tools: ToolDefinition[] = [
    {
      name: "my-tool",
      description: "What this tool does",
      schema: z.object({
        param: z.string().describe("Parameter description")
      }),
      execute: async (args) => {
        // Your logic here
        return JSON.stringify({
          success: true,
          data: "result"
        })
      }
    }
  ]

  return createPlugin(tools)
}

Adding Multiple Tools

Just add more tool definitions to the array:

const tools: ToolDefinition[] = [
  {
    name: "tool-one",
    description: "First tool",
    schema: z.object({ /* ... */ }),
    execute: async (args) => { /* ... */ }
  },
  {
    name: "tool-two",
    description: "Second tool",
    schema: z.object({ /* ... */ }),
    execute: async (args) => { /* ... */ }
  }
]

Using Utilities

Import utilities from @/utils/:

// Example: Using Google Maps
const { GoogleMapsAPI } = await import("@/utils/google-maps")
const maps = new GoogleMapsAPI({ apiKey: process.env.GOOGLE_MAPS_API_KEY })
const result = await maps.geocode("New York")

// Example: Using FAL AI
const { createFalClient } = await import("@/utils/fal")
const fal = createFalClient()

Environment Variables

Add to package.json:

{
  "envVariables": {
    "required": [
      {
        "name": "MY_API_KEY",
        "description": "API key for my service",
        "provider": "My Service",
        "priority": 1
      }
    ],
    "optional": [
      {
        "name": "MY_CONFIG",
        "description": "Optional configuration",
        "provider": "Configuration",
        "priority": 2
      }
    ]
  }
}

Access in code:

const apiKey = process.env.MY_API_KEY

Schema Validation with Zod

Define your parameters with type safety:

schema: z.object({
  // String
  name: z.string().describe("User name"),

  // Optional string with default
  greeting: z.string().optional().default("Hello").describe("Greeting"),

  // Number
  age: z.number().describe("User age"),

  // Enum
  type: z.enum(["user", "admin"]).describe("User type"),

  // Boolean
  active: z.boolean().describe("Is active"),

  // Array
  tags: z.array(z.string()).describe("Tags list")
})

Return Format

Always return JSON string:

// Success
return JSON.stringify({
  success: true,
  data: yourData,
  message: "Operation completed"
})

// Error
return JSON.stringify({
  success: false,
  error: "Error message"
})

That's It!

You now have everything you need to build your own plugin. Keep it simple and add complexity as needed.

For more examples, check out other plugins in the pets/ directory.