Plugins

Plugins ermglichen es Ihnen, OpenCode zu erweitern, indem Sie sich in verschiedene Events einklinken und das Verhalten anpassen. Sie knnen Plugins erstellen, um neue Funktionen hinzuzufgen, externe Dienste zu integrieren oder das Standardverhalten von OpenCode zu ndern.

Beispiele finden Sie in den von der Gemeinschaft erstellten Plugins.

---

Ein Plugin verwenden

Es gibt zwei Mglichkeiten, Plugins zu laden.

---

Aus lokalen Dateien

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

• .opencode/plugin/ - Projektweite Plugins
• ~/.config/opencode/plugin/ - Globale Plugins

Dateien in diesen Verzeichnissen werden beim Start automatisch geladen.

---

Von npm

Geben Sie npm-Pakete in Ihrer Konfigurationsdatei an.

opencode.json

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

Sowohl regulre als auch scoped npm-Pakete werden untersttzt.

Durchsuchen Sie verfgbare Plugins im kosystem.

---

Wie Plugins installiert werden

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

Lokale Plugins werden direkt aus dem Plugin-Verzeichnis geladen. Um externe Pakete zu verwenden, mssen Sie eine package.json in Ihrem Konfigurationsverzeichnis erstellen (siehe Abhngigkeiten), oder das Plugin auf npm verffentlichen und es zu Ihrer Konfiguration hinzufgen.

---

Ladereihenfolge

Plugins werden aus allen Quellen geladen und alle Hooks werden in Reihenfolge ausgefhrt. Die Ladereihenfolge ist:

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

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

---

Ein Plugin erstellen

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

---

Abhngigkeiten

Lokale Plugins und benutzerdefinierte Tools knnen externe npm-Pakete verwenden. Fgen Sie eine package.json zu Ihrem Konfigurationsverzeichnis mit den bentigten Abhngigkeiten hinzu.

.opencode/package.json

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

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

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

---

Grundstruktur

.opencode/plugin/example.js

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

  return {
    // Hook-Implementierungen kommen hierher
  }
}

Die Plugin-Funktion empfngt:

• project: Die aktuellen Projektinformationen.
• directory: Das aktuelle Arbeitsverzeichnis.
• worktree: Der git worktree Pfad.
• client: Ein opencode SDK-Client zur Interaktion mit der KI.
• $: Buns Shell-API zum Ausfhren von Befehlen.

---

TypeScript-Untersttzung

Fr TypeScript-Plugins knnen Sie Typen aus dem Plugin-Paket importieren:

my-plugin.ts

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

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Typsichere Hook-Implementierungen
  }
}

---

Events

Plugins knnen Events abonnieren, wie unten im Beispiele-Abschnitt zu sehen. Hier ist eine Liste der verschiedenen verfgbaren Events.

Command-Events

• command.executed

File-Events

• file.edited
• file.watcher.updated

Installation-Events

• installation.updated

LSP-Events

• lsp.client.diagnostics
• lsp.updated

Message-Events

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

Permission-Events

• permission.replied
• permission.updated

Server-Events

• server.connected

Session-Events

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

Todo-Events

• todo.updated

Tool-Events

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

TUI-Events

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

---

Beispiele

Hier sind einige Beispiele fr Plugins, die Sie verwenden knnen, um opencode zu erweitern.

---

Benachrichtigungen senden

Senden Sie Benachrichtigungen, wenn bestimmte Events eintreten:

.opencode/plugin/notification.js

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

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

Hinweis

Wenn Sie die OpenCode-Desktop-App verwenden, kann sie Systembenachrichtigungen automatisch senden, wenn eine Antwort bereit ist oder wenn eine Sitzung einen Fehler verursacht.

---

.env-Schtzung

Verhindern Sie, dass opencode .env-Dateien liest:

.opencode/plugin/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("Lesen Sie keine .env-Dateien")
      }
    },
  }
}

---

Benutzerdefinierte Tools

Plugins knnen auch benutzerdefinierte Tools zu opencode hinzufgen:

.opencode/plugin/custom-tools.ts

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

export const CustomToolsPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      mytool: tool({
        description: "Dies ist ein benutzerdefiniertes Tool",
        args: {
          foo: tool.schema.string(),
        },
        async execute(args, ctx) {
          return `Hallo ${args.foo}!`
        },
      }),
    },
  }
}

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

• description: Was das Tool tut
• args: Zod-Schema fr die Argumente des Tools
• execute: Funktion, die ausgefhrt wird, wenn das Tool aufgerufen wird

Ihre benutzerdefinierten Tools stehen opencode neben den integrierten Tools zur Verfgung.

---

Protokollierung

Verwenden Sie client.app.log() anstelle von console.log fr strukturiertes Protokollieren:

.opencode/plugin/my-plugin.ts

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

Ebenen: debug, info, warn, error. Siehe SDK-Dokumentation fr Details.

---

Kompaktierungs-Hooks

Passen Sie den Kontext an, der einbezogen wird, wenn eine Sitzung komprimiert wird:

.opencode/plugin/compaction.ts

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

export const CompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Zustzlichen Kontext in den Kompaktierungs-Prompt injizieren
      output.context.push(`
## Benutzerdefinierter Kontext

Fgen Sie jeden Zustand hinzu, der ber die Kompaktierung hinweg bestehen bleiben soll:
- Aktueller Aufgabenstatus
- Wichtige Entscheidungen
- Dateien, an denen aktiv gearbeitet wird
`)
    },
  }
}

Der Hook experimental.session.compacting feuert, bevor das LLM eine Zusammenfassung fr die Fortsetzung generiert. Verwenden Sie ihn, um domnenspezifischen Kontext zu injizieren, den der Standard-Kompaktierungs-Prompt verfehlen wrde.

Sie knnen auch den gesamten Kompaktierungs-Prompt ersetzen, indem Sie output.prompt festlegen:

.opencode/plugin/custom-compaction.ts

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 = `
Sie generieren einen Fortsetzungs-Prompt fr eine Multi-Agent-Schwarm-Sitzung.

Fassen Sie zusammen:
1. Die aktuelle Aufgabe und ihren Status
2. Welche Dateien von wem gendert werden
3. Alle Blockaden oder Abhngigkeiten zwischen Agents
4. Die nchsten Schritte, um die Arbeit abzuschlieen

Formatieren Sie als strukturierter Prompt, den ein neuer Agent verwenden kann, um die Arbeit fortzusetzen.
`
    },
  }
}

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