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

Global config (~/.config/opencode/opencode.json)
Project config (opencode.json)
Global plugin directory (~/.config/opencode/plugins/)
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.

Get Started

Core Concepts

Configuration

Integrations

Extensibility

Interfaces

Advanced

Enterprise

Documentation Index

​Use a plugin

​From local files

​From npm

​How plugins are installed

​Load order

​Create a plugin

​Dependencies

​Basic structure

​TypeScript support

​Plugin API

​Context

​Hooks

​Chat Hooks

​Tool Hooks

​Command Hooks

​Permission Hooks

​Shell Hooks

​Session Hooks

​Event Hook

​Events

​Command Events

​File Events

​Installation Events

​LSP Events

​Message Events

​Permission Events

​Server Events

​Session Events

​Todo Events

​Shell Events

​Tool Events

​TUI Events

​Examples

​Send notifications

​.env protection

​Inject environment variables

​Custom tools

​Logging

​Compaction hooks

Build docs developers (and LLMs) love

Use a plugin

From local files

From npm

How plugins are installed

Load order

Create a plugin

Dependencies

Basic structure

TypeScript support

Plugin API

Context

Hooks

Chat Hooks

Tool Hooks

Command Hooks

Permission Hooks

Shell Hooks

Session Hooks

Event Hook

Events

Command Events

File Events

Installation Events

LSP Events

Message Events

Permission Events

Server Events

Session Events

Todo Events

Shell Events

Tool Events

TUI Events

Examples

Send notifications

.env protection

Inject environment variables

Custom tools

Logging

Compaction hooks