Плагины

Пишите собственные плагины для расширения OpenCode.

Плагины позволяют расширять OpenCode, подключаясь к различным событиям и настраивая поведение. Вы можете создавать плагины, чтобы добавлять новые возможности, интегрироваться с внешними сервисами или изменять стандартное поведение OpenCode.

Примеры смотрите среди плагинов, созданных сообществом.

Использование плагина

Есть два способа загрузки плагинов.

Из локальных файлов

Поместите файлы JavaScript или TypeScript в каталог плагинов.

.opencode/plugins/ — плагины уровня проекта
~/.config/opencode/plugins/ — глобальные плагины

Файлы в этих каталогах автоматически загружаются при запуске.

Из npm

Укажите npm-пакеты в вашем файле конфигурации.

opencode.json

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

Поддерживаются как обычные, так и scoped npm-пакеты.

Просмотрите доступные плагины в экосистеме.

Как устанавливаются плагины

npm-плагины устанавливаются автоматически с помощью Bun при запуске. Пакеты и их зависимости кэшируются в ~/.cache/opencode/node_modules/.

Локальные плагины загружаются непосредственно из каталога плагинов. Чтобы использовать внешние пакеты, вы должны создать package.json внутри вашего каталога конфигурации (см. «Зависимости») или опубликовать плагин в npm и добавить его в конфигурацию.

Порядок загрузки

Плагины загружаются из всех источников, и все хуки выполняются последовательно. Порядок загрузки следующий:

Глобальная конфигурация (~/.config/opencode/opencode.json)
Конфигурация проекта (opencode.json)
Глобальный каталог плагинов (~/.config/opencode/plugins/)
Каталог плагинов проекта (.opencode/plugins/)

Дублирующиеся npm-пакеты с одинаковым именем и версией загружаются один раз. Однако локальный плагин и npm-плагин с похожими именами оба загружаются отдельно.

Создание плагина

Плагин — это модуль JavaScript/TypeScript, который экспортирует одну или несколько функций плагина. Каждая функция получает объект контекста и возвращает объект хуков.

Зависимости

Локальные плагины и пользовательские инструменты могут использовать внешние npm-пакеты. Добавьте package.json в ваш каталог конфигурации с нужными зависимостями.

.opencode/package.json

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

OpenCode запускает bun install при запуске, чтобы установить их. Затем ваши плагины и инструменты могут их импортировать.

.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)
      }
    },
  }
}

Базовая структура

.opencode/plugins/example.js

export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")
 
  return {
    // Hook implementations go here
  }
}

Функция плагина получает:

project — информацию о текущем проекте.
directory — текущий рабочий каталог.
worktree — путь к git worktree.
client — клиент opencode SDK для взаимодействия с ИИ.
$ — shell API (opens in a new tab) Bun для выполнения команд.

Поддержка TypeScript

Для плагинов на TypeScript вы можете импортировать типы из пакета плагина:

my-plugin.ts

import type { Plugin } from "@opencode-ai/plugin"
 
export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hook implementations
  }
}

События

Плагины могут подписываться на события, как показано ниже в разделе «Примеры». Вот список различных доступных событий.

События команд

command.executed

События файлов

file.edited
file.watcher.updated

События установки

installation.updated

События LSP

lsp.client.diagnostics
lsp.updated

События сообщений

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

События разрешений

permission.asked
permission.replied

События сервера

server.connected

События сессий

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

События задач

todo.updated

События оболочки

shell.env

События инструментов

tool.execute.after
tool.execute.before

События TUI

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

Примеры

Вот несколько примеров плагинов, которые вы можете использовать для расширения opencode.

Отправка уведомлений

Отправляйте уведомления при возникновении определённых событий:

.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"'`
      }
    },
  }
}

Мы используем osascript для запуска AppleScript на macOS. Здесь мы используем его для отправки уведомлений.

Примечание: Если вы используете настольное приложение OpenCode, оно может автоматически отправлять системные уведомления, когда ответ готов или когда в сессии возникает ошибка.

Защита .env

Запретите opencode читать файлы .env:

.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")
      }
    },
  }
}

Внедрение переменных окружения

Внедряйте переменные окружения во все выполнения оболочки (инструменты ИИ и пользовательские терминалы):

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

Пользовательские инструменты

Плагины также могут добавлять пользовательские инструменты в 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})`
        },
      }),
    },
  }
}

Помощник tool создаёт пользовательский инструмент, который opencode может вызывать. Он принимает функцию Zod-схемы и возвращает определение инструмента с:

description — что делает инструмент
args — Zod-схема для аргументов инструмента
execute — функция, которая выполняется при вызове инструмента

Ваши пользовательские инструменты будут доступны opencode наряду со встроенными инструментами.

Примечание: Если инструмент плагина использует то же имя, что и встроенный инструмент, инструмент плагина имеет приоритет.

Логирование

Используйте client.app.log() вместо console.log для структурированного логирования:

.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" },
    },
  })
}

Уровни: debug, info, warn, error. Подробности см. в документации SDK (opens in a new tab).

Хуки сжатия

Настройте контекст, включаемый при сжатии сессии:

.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
`)
    },
  }
}

Хук experimental.session.compacting срабатывает до того, как LLM генерирует резюме-продолжение. Используйте его, чтобы внедрить специфичный для предметной области контекст, который стандартный промпт сжатия упустил бы.

Вы также можете полностью заменить промпт сжатия, задав 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.
`
    },
  }
}

Когда output.prompt задан, он полностью заменяет стандартный промпт сжатия. Массив output.context в этом случае игнорируется.

Сервер Экосистема