Plugin

I plugin ti permettono di estendere OpenCode agganciandoti a vari eventi e personalizzando il comportamento. Puoi creare plugin per aggiungere nuove funzionalita’, integrare servizi esterni o modificare il comportamento predefinito di OpenCode.

Per esempi, dai un’occhiata ai plugin creati dalla community.

---

Usare un plugin

Ci sono due modi per caricare i plugin.

---

Da file locali

Metti file JavaScript o TypeScript nella directory dei plugin.

• .opencode/plugins/ - plugin a livello progetto
• ~/.config/opencode/plugins/ - plugin globali

I file in queste directory vengono caricati automaticamente all’avvio.

---

Da npm

Specifica i pacchetti npm nel tuo file di configurazione.

opencode.json

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

Sono supportati sia pacchetti npm normali sia scoped.

Sfoglia i plugin disponibili nell’ecosistema.

---

Come vengono installati i plugin

I plugin npm vengono installati automaticamente usando Bun all’avvio. I pacchetti e le loro dipendenze vengono cache-ati in ~/.cache/opencode/node_modules/.

I plugin locali vengono caricati direttamente dalla directory dei plugin. Per usare pacchetti esterni, devi creare un package.json nella directory di configurazione (vedi Dipendenze) oppure pubblicare il plugin su npm e aggiungerlo alla configurazione.

---

Ordine di caricamento

I plugin vengono caricati da tutte le sorgenti e tutti gli hook vengono eseguiti in sequenza. L’ordine di caricamento e’:

1. Config globale (~/.config/opencode/opencode.json)
2. Config di progetto (opencode.json)
3. Directory plugin globale (~/.config/opencode/plugins/)
4. Directory plugin di progetto (.opencode/plugins/)

I pacchetti npm duplicati con lo stesso nome e versione vengono caricati una sola volta. Tuttavia, un plugin locale e un plugin npm con nomi simili vengono entrambi caricati separatamente.

---

Creare un plugin

Un plugin e’ un modulo JavaScript/TypeScript che esporta una o piu’ funzioni di plugin. Ogni funzione riceve un oggetto di contesto e restituisce un oggetto di hook.

---

Dipendenze

I plugin locali e gli strumenti personalizzati possono usare pacchetti npm esterni. Aggiungi un package.json alla tua directory di configurazione con le dipendenze di cui hai bisogno.

.opencode/package.json

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

OpenCode esegue bun install all’avvio per installarle. I tuoi plugin e strumenti potranno poi importarle.

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

---

Struttura base

.opencode/plugins/example.js

export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")

  return {
    // Hook implementations go here
  }
}

La funzione del plugin riceve:

• project: informazioni sul progetto corrente.
• directory: la working directory corrente.
• worktree: il path del worktree git.
• client: un client SDK di opencode per interagire con l’AI.
• $: la shell API di Bun per eseguire comandi.

---

Supporto TypeScript

Per i plugin TypeScript, puoi importare i tipi dal pacchetto plugin:

my-plugin.ts

import type { Plugin } from "@opencode-ai/plugin"

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hook implementations
  }
}

---

Eventi

I plugin possono sottoscrivere eventi come mostrato sotto nella sezione Esempi. Ecco l’elenco dei diversi eventi disponibili.

Eventi dei comandi

• command.executed

Eventi dei file

• file.edited
• file.watcher.updated

Eventi di installazione

• installation.updated

Eventi LSP

• lsp.client.diagnostics
• lsp.updated

Eventi dei messaggi

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

Eventi dei permessi

• permission.asked
• permission.replied

Eventi del server

• server.connected

Eventi delle sessioni

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

Eventi della todo

• todo.updated

Eventi della shell

• shell.env

Eventi degli strumenti

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

Eventi TUI

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

---

Esempi

Ecco alcuni esempi di plugin che puoi usare per estendere opencode.

---

Invia notifiche

Invia notifiche quando avvengono certi eventi:

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

Stiamo usando osascript per eseguire AppleScript su macOS. Qui lo usiamo per inviare notifiche.

Nota

Se usi l’app desktop di OpenCode, puo’ inviare automaticamente notifiche di sistema quando una risposta e’ pronta o quando una sessione va in errore.

---

Protezione .env

Impedisci a opencode di leggere i file .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")
      }
    },
  }
}

---

Inietta variabili d’ambiente

Inietta variabili d’ambiente in tutte le esecuzioni di shell (strumenti AI e terminale utente):

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

---

Strumenti personalizzati

I plugin possono anche aggiungere strumenti personalizzati a 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})`
        },
      }),
    },
  }
}

L’helper tool crea uno strumento personalizzato che opencode puo’ chiamare. Accetta una funzione di schema Zod e restituisce una definizione di tool con:

• description: cosa fa lo strumento
• args: schema Zod per gli argomenti dello strumento
• execute: funzione eseguita quando lo strumento viene chiamato

I tuoi strumenti personalizzati saranno disponibili in opencode insieme agli strumenti integrati.

---

Logging

Usa client.app.log() invece di console.log per logging strutturato:

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

Livelli: debug, info, warn, error. Vedi la documentazione SDK per i dettagli.

---

Hook di compaction

Personalizza il contesto incluso quando una sessione viene compattata:

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

L’hook experimental.session.compacting scatta prima che l’LLM generi un riassunto di continuazione. Usalo per iniettare contesto specifico di dominio che il prompt di compaction predefinito potrebbe non includere.

Puoi anche sostituire completamente il prompt di compaction impostando 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.
`
    },
  }
}

Quando output.prompt e’ impostato, sostituisce completamente il prompt di compaction predefinito. In questo caso l’array output.context viene ignorato.