Plugins

Plugins lar deg utvide OpenCode ved å koble til ulike arrangementer og tilpasse atferd. Du kan lage plugins for å legge til nye funksjoner, integrere med eksterne tjenester eller endre standardoppførselen til OpenCode.

For eksempler, sjekk ut plugins opprettet av fellesskapet.

---

Bruk en plugin

Det er to måter å laste inn plugins.

---

Fra lokale filer

Plasser JavaScript- eller TypeScript-filer i plugin-katalogen.

• .opencode/plugins/ - Programtillegg på prosjektnivå
• ~/.config/opencode/plugins/ - Globale plugins

Filer i disse katalogene lastes automatisk ved oppstart.

---

Fra npm

Spesifiser npm-pakker i konfigurasjonsfilen.

opencode.json

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

Både vanlige og scoped npm-pakker støttes.

Bla gjennom tilgjengelige plugins i økosystemet.

---

Hvordan plugins installeres

npm-plugins installeres automatisk ved hjelp av Bun ved oppstart. Pakker og deres avhengigheter er bufret i ~/.cache/opencode/node_modules/.

Lokale plugins lastes direkte fra plugin-katalogen. For å bruke eksterne pakker, må du opprette en package.json i konfigurasjonskatalogen din (se Dependencies), eller publisere plugin-en til npm og legg den til i konfigurasjonen din.

---

Lasterekkefølge

Plugins lastes inn fra alle kilder og alle kroker kjøres i rekkefølge. Lastrekkefølgen er:

1. Global konfigurasjon (~/.config/opencode/opencode.json)
2. Prosjektkonfigurasjon (opencode.json)
3. Global plugin-katalog (~/.config/opencode/plugins/)
4. Prosjektpluginkatalog (.opencode/plugins/)

Dupliserte npm-pakker med samme navn og versjon lastes inn én gang. Imidlertid lastes en lokal plugin og en npm plugin med lignende navn begge separat.

---

Opprett en plugin

En plugin er en JavaScript/TypeScript-modul som eksporterer en eller flere plugin-moduler funksjoner. Hver funksjon mottar et kontekstobjekt og returnerer et krokobjekt.

---

Avhengigheter

Lokale plugins og tilpassede verktøy kan bruke eksterne npm-pakker. Legg til en package.json til konfigurasjonskatalogen med avhengighetene du trenger.

.opencode/package.json

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

OpenCode kjører bun install ved oppstart for å installere disse. Programtilleggene og verktøyene dine kan deretter importere dem.

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

---

Grunnleggende struktur

.opencode/plugins/example.js

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

  return {
    // Hook implementations go here
  }
}

Plugin-funksjonen mottar:

• project: Gjeldende prosjektinformasjon.
• directory: Gjeldende arbeidskatalog.
• worktree: Git-arbeidstrebanen.
• client: En OpenCode SDK klient for samhandling med AI.
• $: Buns shell API for å utføre kommandoer.

---

TypeScript-støtte

For TypeScript-plugins kan du importere typer fra plugin-pakken:

my-plugin.ts

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

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

---

Hendelser

Plugins kan abonnere på arrangementer som vist nedenfor i Eksempler-delen. Her er en liste over de forskjellige arrangementene som er tilgjengelige.

Kommandohendelser

• command.executed

Filhendelser

• file.edited
• file.watcher.updated

Installasjonshendelser

• installation.updated

LSP Hendelser

• lsp.client.diagnostics
• lsp.updated

Meldingshendelser

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

Tillatelseshendelser

• permission.asked
• permission.replied

Serverhendelser

• server.connected

Sesjonshendelser

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

Todo-hendelser

• todo.updated

Shell-hendelser

• shell.env

Verktøyhendelser

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

TUI Hendelser

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

---

Eksempler

Her er noen eksempler på plugins du kan bruke for å utvide OpenCode.

---

Send varsler

Send varsler når visse hendelser inntreffer:

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

Vi bruker osascript for å kjøre AppleScript på macOS. Her bruker vi den til å sende varsler.

Merknad

Hvis du bruker OpenCode-skrivebordsappen, kan den sende systemvarsler automatisk når et svar er klart eller når en økt feiler.

---

.env-beskyttelse

Hindre OpenCode fra å lese .env filer:

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

---

Injiser miljøvariabler

Injiser miljøvariabler i all shell-utførelse (AI-verktøy og brukerterminaler):

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

---

Egendefinerte verktøy

Plugins kan også legge til egendefinerte verktøy til 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-hjelperen lager et tilpasset verktøy som OpenCode kan kalle. Den tar en Zod-skjemafunksjon og returnerer en verktøydefinisjon med:

• description: Hva verktøyet gjør
• args: Zod-skjema for verktøyets argumenter
• execute: Funksjon som kjører når verktøyet kalles

Dine egendefinerte verktøy vil være tilgjengelige for å OpenCode sammen med innebygde verktøy.

---

Logging

Bruk client.app.log() i stedet for console.log for strukturert logging:

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

Nivåer: debug, info, warn, error. Se SDK dokumentasjon for detaljer.

---

Komprimeringskroker

Tilpass konteksten inkludert når en økt komprimeres:

.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-kroken avfyres før LLM genererer et fortsettelsessammendrag. Bruk den til å injisere domenespesifikk kontekst som standard komprimeringsforespørsel ville gå glipp av.

Du kan også erstatte komprimeringsmeldingen helt ved å stille inn 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.
`
    },
  }
}

Når output.prompt er angitt, erstatter den standard komprimeringsprompt fullstendig. output.context-matrisen ignoreres i dette tilfellet.