Pet Plugin Template

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

Quick Start

$3

``bash


From pets directory


cp -r _TEMPLATE_ my-plugin
cd my-plugin
`

$3

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

`bash
npm install
npm run quickstart
`

Basic Structure

`typescript
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:

`typescript
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/:

`typescript
// 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:

`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:

`typescript
const apiKey = process.env.MY_API_KEY
`

Schema Validation with Zod

Define your parameters with type safety:

`typescript
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:

`typescript
// 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.