Plugins

Write your own plugins to extend OpenCode.

Plugins allow you to extend OpenCode by hooking into various events and customizing behavior. You can create plugins to add new features, integrate with external services, or modify OpenCode’s default behavior.

For examples, check out the plugins created by the community.

---

Use a plugin

There are two ways to load plugins.

From local files

Place JavaScript or TypeScript files in the plugin directory.

• .opencode/plugins/ - Project-level plugins
• ~/.config/opencode/plugins/ - Global plugins

Files in these directories are automatically loaded at startup.

From npm

Specify npm packages in your config file.

opencode.json

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

Both regular and scoped npm packages are supported.

Browse available plugins in the ecosystem.

How plugins are installed

npm plugins are installed automatically using Bun at startup. Packages and their dependencies are cached in ~/.cache/opencode/node_modules/.

Local plugins are loaded directly from the plugin directory. To use external packages, you must create a package.json within your config directory (see Dependencies), or publish the plugin to npm and add it to your config.

Load order

Plugins are loaded from all sources and all hooks run in sequence. The load order is:

1. Global config (~/.config/opencode/opencode.json)
2. Project config (opencode.json)
3. Global plugin directory (~/.config/opencode/plugins/)
4. Project plugin directory (.opencode/plugins/)

Duplicate npm packages with the same name and version are loaded once. However, a local plugin and an npm plugin with similar names are both loaded separately.

---

Create a plugin

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.

Dependencies

Local plugins and custom tools can use external npm packages. Add a package.json to your config directory with the dependencies you need.

.opencode/package.json

{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}

OpenCode runs bun install at startup to install these. Your plugins and tools can then import them.

.opencode/plugins/my-plugin.ts

import { escape } from "shescape"

export const MyPlugin = async (ctx) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "bash") {
        output.args.command = escape(output.args.command)
      }
    },
  }
}

Basic structure

.opencode/plugins/example.js

export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")

  return {
    // Hook implementations go here
  }
}

The plugin function receives:

• project: The current project information.
• directory: The current working directory.
• worktree: The git worktree path.
• client: An opencode SDK client for interacting with the AI.
• $: Bun’s shell API for executing commands.

TypeScript support

For TypeScript plugins, you can import types from the plugin package:

my-plugin.ts

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

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

---

Plugin API

Context

The plugin function receives a PluginInput context object:

type PluginInput = {
  client: ReturnType<typeof createOpencodeClient>
  project: Project
  directory: string
  worktree: string
  serverUrl: URL
  $: BunShell
}

• client: SDK client for interacting with OpenCode’s API
• project: Current project metadata
• directory: Current working directory for the session
• worktree: Git worktree root path
• serverUrl: OpenCode server URL
• $: Bun’s shell interface for executing commands

Hooks

Plugins return a Hooks object with event handlers. All hooks are optional.

Chat Hooks

chat.message: Modify messages before they’re sent to the LLM

"chat.message": async (input, output) => {
  // input: { sessionID, agent?, model?, messageID?, variant? }
  // output: { message: UserMessage, parts: Part[] }
  output.parts.push({ type: "text", text: "Additional context" })
}

chat.params: Modify LLM parameters (temperature, topP, topK)

"chat.params": async (input, output) => {
  // input: { sessionID, agent, model, provider, message }
  // output: { temperature, topP, topK, options }
  output.temperature = 0.7
}

chat.headers: Add custom headers to LLM requests

"chat.headers": async (input, output) => {
  // input: { sessionID, agent, model, provider, message }
  // output: { headers }
  output.headers["X-Custom-Header"] = "value"
}

Tool Hooks

tool.execute.before: Intercept tool calls before execution

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

tool.execute.after: Modify tool results after execution

"tool.execute.after": async (input, output) => {
  // input: { tool, sessionID, callID, args }
  // output: { title, output, metadata }
  if (input.tool === "bash") {
    output.metadata = { exitCode: 0 }
  }
}

tool.definition: Modify tool definitions sent to the LLM

"tool.definition": async (input, output) => {
  // input: { toolID }
  // output: { description, parameters }
  if (input.toolID === "bash") {
    output.description = "Custom bash description"
  }
}

tool: Register custom tools

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

return {
  tool: {
    mytool: tool({
      description: "This is a custom tool",
      args: {
        foo: tool.schema.string(),
      },
      async execute(args, context) {
        return `Hello ${args.foo}!`
      },
    }),
  },
}

Command Hooks

command.execute.before: Modify commands before execution

"command.execute.before": async (input, output) => {
  // input: { command, sessionID, arguments }
  // output: { parts }
  output.parts.push({ type: "text", text: "Extra instructions" })
}

Permission Hooks

permission.ask: Override permission decisions

"permission.ask": async (input, output) => {
  // input: Permission
  // output: { status: "ask" | "deny" | "allow" }
  if (input.type === "file" && input.path.includes(".env")) {
    output.status = "deny"
  }
}

Shell Hooks

shell.env: Inject environment variables into shell execution

"shell.env": async (input, output) => {
  // input: { cwd, sessionID?, callID? }
  // output: { env }
  output.env.MY_API_KEY = "secret"
  output.env.PROJECT_ROOT = input.cwd
}

Session Hooks

experimental.session.compacting: Customize session compaction

"experimental.session.compacting": async (input, output) => {
  // input: { sessionID }
  // output: { context: string[], prompt?: string }
  output.context.push("Custom context for compaction")
}

Event Hook

event: Listen to all OpenCode events

event: async ({ event }) => {
  if (event.type === "session.idle") {
    console.log("Session completed!")
  }
}

---

Events

Plugins can subscribe to events using the event hook. Here is a list of the different events available.

Command Events

• command.executed

File Events

• file.edited
• file.watcher.updated

Installation Events

• installation.updated

LSP Events

• lsp.client.diagnostics
• lsp.updated

Message Events

• message.part.removed
• message.part.updated
• message.removed
• message.updated

Permission Events

• permission.asked
• permission.replied

Server Events

• server.connected

Session Events

• session.created
• session.compacted
• session.deleted
• session.diff
• session.error
• session.idle
• session.status
• session.updated

Todo Events

• todo.updated

Shell Events

• shell.env

Tool Events

• tool.execute.after
• tool.execute.before

TUI Events

• tui.prompt.append
• tui.command.execute
• tui.toast.show

---

Examples

Here are some examples of plugins you can use to extend opencode.

Send notifications

Send notifications when certain events occur:

.opencode/plugins/notification.js

export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    event: async ({ event }) => {
      // Send notification on session completion
      if (event.type === "session.idle") {
        await $`osascript -e 'display notification "Session completed!" with title "opencode"'`
      }
    },
  }
}

We are using osascript to run AppleScript on macOS. Here we are using it to send notifications.

If you’re using the OpenCode desktop app, it can send system notifications automatically when a response is ready or when a session errors.

.env protection

Prevent opencode from reading .env files:

.opencode/plugins/env-protection.js

export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    },
  }
}

Inject environment variables

Inject environment variables into all shell execution (AI tools and user terminals):

.opencode/plugins/inject-env.js

export const InjectEnvPlugin = async () => {
  return {
    "shell.env": async (input, output) => {
      output.env.MY_API_KEY = "secret"
      output.env.PROJECT_ROOT = input.cwd
    },
  }
}

Custom tools

Plugins can also add custom tools to opencode:

.opencode/plugins/custom-tools.ts

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, context) {
          const { directory, worktree } = context
          return `Hello ${args.foo} from ${directory} (worktree: ${worktree})`
        },
      }),
    },
  }
}

The tool helper creates a custom tool that opencode can call. It takes a Zod schema function and returns a tool definition with:

• description: What the tool does
• args: Zod schema for the tool’s arguments
• execute: Function that runs when the tool is called

Your custom tools will be available to opencode alongside built-in tools.

Logging

Use client.app.log() instead of console.log for structured logging:

.opencode/plugins/my-plugin.ts

export const MyPlugin = async ({ client }) => {
  await client.app.log({
    body: {
      service: "my-plugin",
      level: "info",
      message: "Plugin initialized",
      extra: { foo: "bar" },
    },
  })
}

Levels: debug, info, warn, error. See SDK documentation for details.

Compaction hooks

Customize the context included when a session is compacted:

.opencode/plugins/compaction.ts

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

export const CompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Inject additional context into the compaction prompt
      output.context.push(`
## Custom Context

Include any state that should persist across compaction:
- Current task status
- Important decisions made
- Files being actively worked on
`)
    },
  }
}

The experimental.session.compacting hook fires before the LLM generates a continuation summary. Use it to inject domain-specific context that the default compaction prompt would miss.

You can also replace the compaction prompt entirely by setting output.prompt:

.opencode/plugins/custom-compaction.ts

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

export const CustomCompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Replace the entire compaction prompt
      output.prompt = `
You are generating a continuation prompt for a multi-agent swarm session.

Summarize:
1. The current task and its status
2. Which files are being modified and by whom
3. Any blockers or dependencies between agents
4. The next steps to complete the work

Format as a structured prompt that a new agent can use to resume work.
`
    },
  }
}

When output.prompt is set, it completely replaces the default compaction prompt. The output.context array is ignored in this case.