Plugins

Escreva seus proprios plugins para estender o OpenCode.

Os plugins permitem que voce estenda o OpenCode conectando-se a varios eventos e personalizando o comportamento. Voce pode criar plugins para adicionar novos recursos, integrar com servicos externos ou modificar o comportamento padrao do OpenCode.

Confira os plugins criados pela comunidade como exemplos.

Usar um plugin

Existem duas maneiras de carregar plugins.

De arquivos locais

Coloque arquivos JavaScript ou TypeScript no diretorio de plugins.

• .opencode/plugins/ - Plugins no nivel do projeto
• ~/.config/opencode/plugins/ - Plugins globais

Os arquivos nesses diretorios sao carregados automaticamente na inicializacao.

Do npm

Especifique pacotes npm no seu arquivo de configuracao.

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

Tanto pacotes npm regulares quanto com escopo sao suportados.

Navegue pelos plugins disponiveis no ecossistema.

Como os plugins sao instalados

Plugins npm sao instalados automaticamente usando Bun na inicializacao. Os pacotes e suas dependencias sao armazenados em cache em ~/.cache/opencode/node_modules/.

Plugins locais sao carregados diretamente do diretorio de plugins. Para usar pacotes externos, voce deve criar um package.json dentro do seu diretorio de configuracao (veja Dependencias), ou publicar o plugin no npm e adiciona-lo a sua configuracao.

Ordem de carregamento

Os plugins sao carregados de todas as fontes e todos os hooks sao executados em sequencia. A ordem de carregamento e:

1. Configuracao global (~/.config/opencode/opencode.json)
2. Configuracao do projeto (opencode.json)
3. Diretorio de plugins global (~/.config/opencode/plugins/)
4. Diretorio de plugins do projeto (.opencode/plugins/)

Pacotes npm duplicados com o mesmo nome e versao sao carregados apenas uma vez. No entanto, um plugin local e um plugin npm com nomes semelhantes sao carregados separadamente.

Criar um plugin

Um plugin e um modulo JavaScript/TypeScript que exporta uma ou mais funcoes de plugin. Cada funcao recebe um objeto de contexto e retorna um objeto de hooks.

Dependencias

Plugins locais e ferramentas personalizadas podem usar pacotes npm externos. Adicione um package.json ao seu diretorio de configuracao com as dependencias que voce precisa.

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

O OpenCode executa bun install na inicializacao para instala-las. Seus plugins e ferramentas podem entao importa-las.

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

Estrutura basica

export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")
 
  return {
    // Implementacoes de hooks vao aqui
  }
}

A funcao do plugin recebe:

• project: As informacoes do projeto atual.
• directory: O diretorio de trabalho atual.
• worktree: O caminho do git worktree.
• client: Um cliente SDK do opencode para interagir com a IA.
• $: A shell API (opens in a new tab) do Bun para executar comandos.

Suporte a TypeScript

Para plugins TypeScript, voce pode importar tipos do pacote de plugins:

import type { Plugin } from "@opencode-ai/plugin"
 
export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Implementacoes de hooks com seguranca de tipos
  }
}

Eventos

Os plugins podem se inscrever em eventos como mostrado na secao de Exemplos abaixo. Aqui esta uma lista dos diferentes eventos disponiveis.

Eventos de comando

• command.executed

Eventos de arquivo

• file.edited
• file.watcher.updated

Eventos de instalacao

• installation.updated

Eventos de LSP

• lsp.client.diagnostics
• lsp.updated

Eventos de mensagem

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

Eventos de permissao

• permission.asked
• permission.replied

Eventos de servidor

• server.connected

Eventos de sessao

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

Eventos de tarefas

• todo.updated

Eventos de Shell

• shell.env

Eventos de ferramentas

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

Eventos de TUI

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

Exemplos

Aqui estao alguns exemplos de plugins que voce pode usar para estender o opencode.

Enviar notificacoes

Envie notificacoes quando certos eventos ocorrerem:

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

Estamos usando osascript para executar AppleScript no macOS. Aqui estamos usando para enviar notificacoes.

Nota: Se voce estiver usando o aplicativo desktop do OpenCode, ele pode enviar notificacoes do sistema automaticamente quando uma resposta estiver pronta ou quando uma sessao tiver um erro.

Protecao de .env

Impeca que o opencode leia arquivos .env:

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

Injetar variaveis de ambiente

Injete variaveis de ambiente em todas as execucoes de shell (ferramentas de IA e terminais de usuario):

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

Ferramentas personalizadas

Os plugins tambem podem adicionar ferramentas personalizadas ao opencode:

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

O helper tool cria uma ferramenta personalizada que o opencode pode chamar. Ele recebe uma funcao de schema Zod e retorna uma definicao de ferramenta com:

• description: O que a ferramenta faz
• args: Schema Zod para os argumentos da ferramenta
• execute: Funcao que e executada quando a ferramenta e chamada

Suas ferramentas personalizadas estarao disponiveis no opencode junto com as ferramentas integradas.

Logging

Use client.app.log() em vez de console.log para logging estruturado:

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

Niveis: debug, info, warn, error. Veja a documentacao do SDK (opens in a new tab) para detalhes.

Hooks de compactacao

Personalize o contexto incluido quando uma sessao e compactada:

import type { Plugin } from "@opencode-ai/plugin"
 
export const CompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Injetar contexto adicional no prompt de compactacao
      output.context.push(`
## Custom Context
 
Include any state that should persist across compaction:
- Current task status
- Important decisions made
- Files being actively worked on
`)
    },
  }
}

O hook experimental.session.compacting e disparado antes do LLM gerar um resumo de continuacao. Use-o para injetar contexto especifico do dominio que o prompt de compactacao padrao pode perder.

Voce tambem pode substituir o prompt de compactacao completamente definindo output.prompt:

import type { Plugin } from "@opencode-ai/plugin"
 
export const CustomCompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Substituir todo o prompt de compactacao
      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.
`
    },
  }
}

Quando output.prompt e definido, ele substitui completamente o prompt de compactacao padrao. O array output.context e ignorado neste caso.