OpenCode Plugin System: Hooks, Custom Tools, and Session Control

What OpenCode Plugins Are

OpenCode plugins are async functions that run inside the OpenCode server process. They receive a context object and return an object containing hooks (event interceptors) and/or custom tools (new AI-callable functions). This is the extension mechanism for modifying how OpenCode behaves without forking the project.

Source: opencode.ai/docs/plugins, anomalyco/opencode on GitHub.

Plugin Shape

Every plugin exports a function matching the Plugin type from @opencode-ai/plugin:

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

3
export const MyPlugin: Plugin = async (ctx) => {
4
  return {
5
    // hooks and/or custom tools
6
  }
7
}

The ctx parameter provides:

Available Hooks

Hooks are string-keyed functions in the returned object. Each receives (input, output) — output is mutable.

1
export const EnvProtection: Plugin = async () => ({
2
  "tool.execute.before": async (input, output) => {
3
    if (input.tool === "read" && output.args.filePath.includes(".env")) {
4
      throw new Error("Do not read .env files")
5
    }
6
  }
7
})

1
export const InjectEnv: Plugin = async () => ({
2
  "shell.env": async (input, output) => {
3
    output.env.MY_API_KEY = "secret"
4
    output.env.PROJECT_ROOT = input.cwd
5
  }
6
})

1
export const CompactionPlugin: Plugin = async (ctx) => ({
2
  "experimental.session.compacting": async (input, output) => {
3
    output.context.push(`
4
## Current State
5
- Actively modifying: src/components/Header.vue
6
- Decision: using Composition API with script setup
7
`)
8
  }
9
})

1
export const CustomCompactionPlugin: Plugin = async (ctx) => ({
2
  "experimental.session.compacting": async (input, output) => {
3
    output.prompt = `
4
Summarize: current task, files being modified, blockers, and next steps.
5
Format as a structured prompt for a new agent to resume work.
6
`
7
  }
8
})

Custom Tools

Plugins can register new tools that the AI can call alongside built-in ones. Custom tools take precedence over built-in tools when there’s a name conflict.

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

3
export const CustomToolsPlugin: Plugin = async (ctx) => ({
4
  tool: {
5
    deploy_check: tool({
6
      description: "Check deployment status for a service",
7
      args: {
8
        service: tool.schema.string(),
9
        region: tool.schema.string().optional(),
10
      },
11
      async execute(args, context) {
12
        const { directory } = context
13
        return `Checking ${args.service} in ${args.region ?? "us-east-1"}...`
14
      },
15
    }),
16
  },
17
})

Key details:

• args uses Zod schemas via tool.schema.* (string, number, boolean, optional, etc.)
• execute receives parsed arguments and a context object with directory and worktree
• Return value is a string passed back to the AI

Real-World Examples

Shell escaping with external dependencies:

1
import { escape } from "shescape"
2

3
export const SafeBash: Plugin = async () => ({
4
  "tool.execute.before": async (input, output) => {
5
    if (input.tool === "bash") {
6
      output.args.command = escape(output.args.command)
7
    }
8
  }
9
})

PTY management (opencode-pty) — spawns background terminal sessions as AI-callable tools (pty_spawn, pty_read, pty_write, pty_kill).

Registration

Add plugins to opencode.json in the project root:

1
{
2
  "$schema": "https://opencode.ai/config.json",
3
  "plugin": ["opencode-pty", "opencode-helicone-session", "@my-org/custom-plugin"]
4
}

Supports both regular and scoped npm packages. OpenCode resolves and loads them at startup.

Publishing a Plugin

1
my-opencode-plugin/
2
  package.json         # name: "my-opencode-plugin"
3
  src/
4
    index.ts           # export const MyPlugin: Plugin = ...
5
  tsconfig.json

The package should export a function matching the Plugin type. Consumers add it to their opencode.json plugin array.

Hook Summary

This article was written by opencode (GLM-5-Turbo | Z.AI Coding Plan)