Plugins

Schreiben Sie Ihre eigenen Plugins, um OpenCode zu erweitern.

Plugins ermoglichen es Ihnen, OpenCode zu erweitern, indem Sie sich in verschiedene Events einklinken und das Verhalten anpassen. Sie konnen Plugins erstellen, um neue Funktionen hinzuzufugen, externe Dienste zu integrieren oder das Standardverhalten von OpenCode zu andern.

Schauen Sie sich die von der Community erstellten Plugins als Beispiele an.

Ein Plugin verwenden

Es gibt zwei Moglichkeiten, Plugins zu laden.

Aus lokalen Dateien

Platzieren Sie JavaScript- oder TypeScript-Dateien im Plugin-Verzeichnis.

• .opencode/plugins/ - Projektspezifische Plugins
• ~/.config/opencode/plugins/ - Globale Plugins

Dateien in diesen Verzeichnissen werden beim Start automatisch geladen.

Von npm

Geben Sie npm-Pakete in Ihrer Konfigurationsdatei an.

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

Sowohl regulare als auch Scoped npm-Pakete werden unterstutzt.

Durchsuchen Sie verfugbare Plugins im Okosystem.

Wie Plugins installiert werden

npm-Plugins werden beim Start automatisch mit Bun installiert. Pakete und ihre Abhangigkeiten werden in ~/.cache/opencode/node_modules/ zwischengespeichert.

Lokale Plugins werden direkt aus dem Plugin-Verzeichnis geladen. Um externe Pakete zu verwenden, mussen Sie eine package.json in Ihrem Konfigurationsverzeichnis erstellen (siehe Abhangigkeiten) oder das Plugin auf npm veroffentlichen und zu Ihrer Konfiguration hinzufugen.

Ladereihenfolge

Plugins werden aus allen Quellen geladen und alle Hooks werden der Reihe nach ausgefuhrt. Die Ladereihenfolge ist:

1. Globale Konfiguration (~/.config/opencode/opencode.json)
2. Projektkonfiguration (opencode.json)
3. Globales Plugin-Verzeichnis (~/.config/opencode/plugins/)
4. Projekt-Plugin-Verzeichnis (.opencode/plugins/)

Doppelte npm-Pakete mit demselben Namen und derselben Version werden nur einmal geladen. Ein lokales Plugin und ein npm-Plugin mit ahnlichen Namen werden jedoch separat geladen.

Ein Plugin erstellen

Ein Plugin ist ein JavaScript/TypeScript-Modul, das eine oder mehrere Plugin-Funktionen exportiert. Jede Funktion erhalt ein Kontextobjekt und gibt ein Hooks-Objekt zuruck.

Abhangigkeiten

Lokale Plugins und benutzerdefinierte Tools konnen externe npm-Pakete verwenden. Fugen Sie eine package.json mit den benotigten Abhangigkeiten zu Ihrem Konfigurationsverzeichnis hinzu.

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

OpenCode fuhrt beim Start bun install aus, um diese zu installieren. Ihre Plugins und Tools konnen sie dann importieren.

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

Grundstruktur

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

Die Plugin-Funktion erhalt:

• project: Die aktuellen Projektinformationen.
• directory: Das aktuelle Arbeitsverzeichnis.
• worktree: Der git worktree-Pfad.
• client: Ein opencode SDK-Client fur die Interaktion mit der KI.
• $: Buns shell API (opens in a new tab) zum Ausfuhren von Befehlen.

TypeScript-Unterstutzung

Fur TypeScript-Plugins konnen Sie Typen aus dem Plugin-Paket importieren:

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

Events

Plugins konnen Events abonnieren, wie im Beispielabschnitt unten gezeigt. Hier ist eine Liste der verschiedenen verfugbaren Events.

Befehlsevents

• command.executed

Dateievents

• file.edited
• file.watcher.updated

Installationsevents

• installation.updated

LSP-Events

• lsp.client.diagnostics
• lsp.updated

Nachrichtenevents

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

Berechtigungsevents

• permission.asked
• permission.replied

Serverevents

• server.connected

Sitzungsevents

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

Todo-Events

• todo.updated

Shell-Events

• shell.env

Tool-Events

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

TUI-Events

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

Beispiele

Hier sind einige Beispiele fur Plugins, die Sie verwenden konnen, um opencode zu erweitern.

Benachrichtigungen senden

Senden Sie Benachrichtigungen, wenn bestimmte Events auftreten:

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

Wir verwenden osascript, um AppleScript auf macOS auszufuhren. Hier verwenden wir es, um Benachrichtigungen zu senden.

Hinweis: Wenn Sie die OpenCode Desktop-App verwenden, kann diese automatisch Systembenachrichtigungen senden, wenn eine Antwort bereit ist oder wenn eine Sitzung einen Fehler hat.

.env-Schutz

Verhindern Sie, dass opencode .env-Dateien liest:

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

Umgebungsvariablen injizieren

Injizieren Sie Umgebungsvariablen in alle Shell-Ausfuhrungen (KI-Tools und Benutzerterminals):

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

Benutzerdefinierte Tools

Plugins konnen auch benutzerdefinierte Tools zu opencode hinzufugen:

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

Der tool-Helfer erstellt ein benutzerdefiniertes Tool, das opencode aufrufen kann. Er nimmt eine Zod-Schema-Funktion und gibt eine Tool-Definition zuruck mit:

• description: Was das Tool macht
• args: Zod-Schema fur die Argumente des Tools
• execute: Funktion, die ausgefuhrt wird, wenn das Tool aufgerufen wird

Ihre benutzerdefinierten Tools sind in opencode neben den integrierten Tools verfugbar.

Logging

Verwenden Sie client.app.log() anstelle von console.log fur strukturiertes Logging:

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

Level: debug, info, warn, error. Siehe SDK-Dokumentation (opens in a new tab) fur Details.

Kompaktierungs-Hooks

Passen Sie den Kontext an, der bei der Kompaktierung einer Sitzung enthalten ist:

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

Der experimental.session.compacting-Hook wird ausgelost, bevor das LLM eine Fortsetzungszusammenfassung generiert. Verwenden Sie ihn, um domanenspezifischen Kontext zu injizieren, den der Standard-Kompaktierungs-Prompt moglicherweise ubersieht.

Sie konnen den Kompaktierungs-Prompt auch vollstandig ersetzen, indem Sie output.prompt setzen:

import type { Plugin } from "@opencode-ai/plugin"
 
export const CustomCompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Den gesamten Kompaktierungs-Prompt ersetzen
      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.
`
    },
  }
}

Wenn output.prompt gesetzt ist, ersetzt es den Standard-Kompaktierungs-Prompt vollstandig. Das output.context-Array wird in diesem Fall ignoriert.