Plugins

Escreva seus próprios plugins para estender o OpenCode.

Os plugins permitem que você estenda o OpenCode conectando-se a vários eventos e personalizando o comportamento. Você pode criar plugins para adicionar novos recursos, integrar com serviços externos ou modificar o comportamento padrão do OpenCode.

Para exemplos, confira os plugins criados pela comunidade.

Usar um plugin

Existem duas maneiras de carregar plugins.

A partir de arquivos locais

Coloque arquivos JavaScript ou TypeScript no diretório de plugins.

• .opencode/plugins/ - Plugins no nível do projeto
• ~/.config/opencode/plugins/ - Plugins globais

Os arquivos nesses diretórios são carregados automaticamente na inicialização.

A partir do npm

Especifique pacotes npm no seu arquivo de config.

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

Tanto pacotes npm comuns quanto com escopo são suportados.

Navegue pelos plugins disponíveis no ecossistema.

Como os plugins são instalados

Plugins npm são instalados automaticamente usando o Bun na inicialização. Os pacotes e suas dependências ficam em cache em ~/.cache/opencode/node_modules/.

Plugins locais são carregados diretamente do diretório de plugins. Para usar pacotes externos, você precisa criar um package.json dentro do seu diretório de config (veja Dependências), ou publicar o plugin no npm e adicioná-lo à sua config.

Ordem de carregamento

Os plugins são carregados de todas as fontes e todos os hooks rodam em sequência. A ordem de carregamento é:

1. Config global ( ~/.config/opencode/opencode.json )
2. Config do projeto ( opencode.json )
3. Diretório de plugins global ( ~/.config/opencode/plugins/ )
4. Diretório de plugins do projeto ( .opencode/plugins/ )

Pacotes npm duplicados com o mesmo nome e versão são carregados uma única vez. No entanto, um plugin local e um plugin npm com nomes parecidos são carregados separadamente.

Criar um plugin

Um plugin é um módulo JavaScript/TypeScript que exporta uma ou mais funções de plugin. Cada função recebe um objeto de contexto e retorna um objeto de hooks.

Dependências

Plugins locais e ferramentas personalizadas podem usar pacotes npm externos. Adicione um package.json ao seu diretório de config com as dependências de que você precisa.

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

O OpenCode roda bun install na inicialização para instalá-las. Seus plugins e ferramentas podem então importá-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 básica

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

A função do plugin recebe:

• project : As informações do projeto atual.
• directory : O diretório 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 em TypeScript, você pode importar os tipos do pacote do plugin:

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

Eventos

Os plugins podem se inscrever em eventos, como mostrado na seção de Exemplos abaixo. Aqui está uma lista dos diferentes eventos disponíveis.

Eventos de comando

• command.executed

Eventos de arquivo

• file.edited
• file.watcher.updated

Eventos de instalação

• 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 permissão

• permission.asked
• permission.replied

Eventos de servidor

• server.connected

Eventos de sessão

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

Eventos de todo

• 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 estão alguns exemplos de plugins que você pode usar para estender o opencode.

Enviar notificações

Envie notificações quando certos eventos ocorrerem:

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

Estamos usando o osascript para executar AppleScript no macOS. Aqui o usamos para enviar notificações.

Nota: Se você estiver usando o app desktop do OpenCode, ele pode enviar notificações do sistema automaticamente quando uma resposta estiver pronta ou quando uma sessão tiver um erro.

Proteção de .env

Impeça 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 variáveis de ambiente

Injete variáveis de ambiente em todas as execuções de shell (ferramentas de IA e terminais do usuário):

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 também 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 função de schema do Zod e retorna uma definição de ferramenta com:

• description : O que a ferramenta faz
• args : Schema do Zod para os argumentos da ferramenta
• execute : Função que roda quando a ferramenta é chamada

Suas ferramentas personalizadas ficarão disponíveis para o opencode ao lado das ferramentas integradas.

Nota: Se uma ferramenta de plugin usar o mesmo nome de uma ferramenta integrada, a ferramenta do plugin tem precedência.

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

Níveis: debug, info, warn, error. Veja a documentação do SDK (opens in a new tab) para detalhes.

Hooks de compactação

Personalize o contexto incluído quando uma sessão é compactada:

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

O hook experimental.session.compacting é disparado antes de o LLM gerar um resumo de continuação. Use-o para injetar contexto específico do domínio que o prompt de compactação padrão deixaria passar.

Você também pode substituir o prompt de compactação por completo definindo output.prompt:

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

Quando output.prompt é definido, ele substitui completamente o prompt de compactação padrão. O array output.context é ignorado nesse caso.