Plugins

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
  }
}

---

Events

Plugins can subscribe to events as seen below in the Examples section. 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.

Note

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 {