---
title: Plugins
description: Escreva seus próprios plugins para estender o OpenCode.
---

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-se a serviços externos ou modificar o comportamento padrão do OpenCode.

Para exemplos, confira os [plugins](/docs/ecosystem#plugins) criados pela comunidade.

---

## Usar um plugin

Existem duas maneiras de carregar plugins.

---

### De arquivos locais

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

- `.opencode/plugins/` - Plugins em nível de projeto
- `~/.config/opencode/plugins/` - Plugins globais

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

---

### Do npm

Especifique pacotes npm no seu arquivo de configuração.

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

Pacotes npm regulares e escopados são suportados.

Navegue pelos plugins disponíveis no [ecossistema](/docs/ecosystem#plugins).

---

### Como os plugins são instalados

**Plugins npm** são instalados automaticamente usando Bun na inicialização. Pacotes e suas dependências são armazenados em cache em `~/.cache/opencode/node_modules/`.

**Plugins locais** são carregados diretamente do diretório de plugins. Para usar pacotes externos, você deve criar um `package.json` dentro do seu diretório de configuração (veja [Dependências](#dependencies)), ou publicar o plugin no npm e [adicioná-lo à sua configuração](/docs/config#plugins).

---

### Ordem de carregamento

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

1. Configuração global (`~/.config/opencode/opencode.json`)
2. Configuração 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 vez. No entanto, um plugin local e um plugin npm com nomes semelhantes 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 configuração com as dependências necessárias.

```json title=".opencode/package.json"
{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}
```

O OpenCode executa `bun install` na inicialização para instalar esses pacotes. Seus plugins e ferramentas podem então importá-los.

```ts title=".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)
      }
    },
  }
}
```

---

### Estrutura básica

```js title=".opencode/plugins/example.js"
export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin inicializado!")

  return {
    // Implementações de hooks vão aqui
  }
}
```

A função do plugin recebe:

- `project`: As informações do projeto atual.
- `directory`: O diretório de trabalho atual.
- `worktree`: O caminho do worktree do git.
- `client`: Um cliente SDK do opencode para interagir com a IA.
- `$`: A [API shell](https://bun.com/docs/runtime/shell) do Bun para executar comandos.

---

### Suporte a TypeScript

Para plugins TypeScript, você pode importar tipos do pacote de plugin:

```ts title="my-plugin.ts" {1}
import type { Plugin } from "@opencode-ai/plugin"

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Implementações de hooks seguras em tipo
  }
}
```

---

### Eventos

Plugins podem se inscrever em eventos como visto abaixo na seção Exemplos. 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 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 Ferramenta

- `tool.execute.after`
- `tool.execute.before`

#### Eventos 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:

```js title=".opencode/plugins/notification.js"
export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    event: async ({ event }) => {
      // Enviar notificação ao concluir a sessão
      if (event.type === "session.idle") {
        await $`osascript -e 'display notification "Sessão concluída!" with title "opencode"'`
      }
    },
  }
}
```

Estamos usando `osascript` para executar AppleScript no macOS. Aqui estamos usando para enviar notificações.

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

---

### Proteção .env

Impeça o opencode de ler arquivos `.env`:

```javascript title=".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("Não leia arquivos .env")
      }
    },
  }
}
```

---

### Injetar variáveis de ambiente

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

```javascript title=".opencode/plugins/inject-env.js"
export const InjectEnvPlugin = async () => {
  return {
    "shell.env": async (input, output) => {
      output.env.MY_API_KEY = "secreto"
      output.env.PROJECT_ROOT = input.cwd
    },
  }
}
```

---

### Ferramentas personalizadas

Plugins também podem adicionar ferramentas personalizadas ao opencode:

```ts title=".opencode/plugins/custom-tools.ts"
import { type Plugin, tool } from "@opencode-ai/plugin"

export const CustomToolsPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      mytool: tool({
        description: "Esta é uma ferramenta personalizada",
        args: {
          foo: tool.schema.string(),
        },
        async execute(args, context) {
          const { directory, worktree } = context
          return `Olá ${args.foo} de ${directory} (worktree: ${worktree})`
        },
      }),
    },
  }
}
```

O helper `tool` cria uma ferramenta personalizada que o opencode pode chamar. Ele aceita uma função de esquema Zod e retorna uma definição de ferramenta com:

- `description`: O que a ferramenta faz
- `args`: Esquema Zod para os argumentos da ferramenta
- `execute`: Função que é executada quando a ferramenta é chamada

Suas ferramentas personalizadas estarão disponíveis para o opencode junto com as ferramentas integradas.

---

### Registro

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

```ts title=".opencode/plugins/my-plugin.ts"
export const MyPlugin = async ({ client }) => {
  await client.app.log({
    body: {
      service: "my-plugin",
      level: "info",
      message: "Plugin inicializado",
      extra: { foo: "bar" },
    },
  })
}
```

Níveis: `debug`, `info`, `warn`, `error`. Veja a [documentação do SDK](https://opencode.ai/docs/sdk) para detalhes.

---

### Hooks de compactação

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

```ts title=".opencode/plugins/compaction.ts"
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 compactação
      output.context.push(`
## Contexto Personalizado

Inclua qualquer estado que deve persistir entre as compactações:
- Status da tarefa atual
- Decisões importantes tomadas
- Arquivos sendo trabalhados ativamente
`)
    },
  }
}
```

O hook `experimental.session.compacting` é acionado antes que o LLM gere um resumo de continuação. Use-o para injetar contexto específico de domínio que o prompt de compactação padrão poderia perder.

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

```ts title=".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) => {
      // Substituir todo o prompt de compactação
      output.prompt = `
Você está gerando um prompt de continuação para uma sessão de enxame multi-agente.

Resuma:
1. A tarefa atual e seu status
2. Quais arquivos estão sendo modificados e por quem
3. Quaisquer bloqueios ou dependências entre agentes
4. Os próximos passos para concluir o trabalho

Formate como um prompt estruturado que um novo agente pode usar para retomar o trabalho.
`
    },
  }
}
```

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