Aller au contenu
OpenCode
app.header.homeapp.header.docs

Plugins

Écrivez vos propres plugins pour étendre OpenCode.

Les plugins vous permettent d’étendre OpenCode en vous connectant à divers événements et en personnalisant le comportement. Vous pouvez créer des plugins pour ajouter de nouvelles fonctionnalités, intégrer des services externes ou modifier le comportement par défaut de OpenCode.

Pour des exemples, consultez les plugins créés par la communauté.

Utiliser un plugin

Il existe deux manières de charger des plugins.

À partir de fichiers locaux

Placez les fichiers JavaScript ou TypeScript dans le répertoire du plugin.

  • .opencode/plugins/ - Plugins au niveau du projet
  • ~/.config/opencode/plugins/ - Plugins globaux

Les fichiers de ces répertoires sont automatiquement chargés au démarrage.

De npm

Spécifiez les packages npm dans votre fichier de configuration.

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

Les packages npm standards et étendus sont pris en charge.

Parcourez les plugins disponibles dans le ecosystem.

Comment les plugins sont installés

Les plugins npm sont installés automatiquement à l’aide de Bun au démarrage. Les packages et leurs dépendances sont mis en cache dans ~/.cache/opencode/node_modules/.

Les plugins locaux sont chargés directement depuis le répertoire des plugins. Pour utiliser des packages externes, vous devez créer un package.json dans votre répertoire de configuration (voir Dépendances), ou publier le plugin sur npm et l’ajouter à votre config.

Ordre de chargement

Les plugins sont chargés à partir de toutes les sources et tous les hooks s’exécutent dans l’ordre. L’ordre de chargement est le suivant :

  1. Configuration globale (~/.config/opencode/opencode.json)
  2. Configuration du projet (opencode.json)
  3. Répertoire global des plugins (~/.config/opencode/plugins/)
  4. Répertoire des plugins du projet (.opencode/plugins/)

Les packages npm en double avec le même nom et la même version sont chargés une fois. Cependant, un plugin local et un plugin npm portant des noms similaires sont tous deux chargés séparément.

Créer un plugin

Un plugin est un module JavaScript/TypeScript qui exporte un ou plusieurs plugins fonctions. Chaque fonction reçoit un objet contextuel et renvoie un objet hooks.

Dépendances

Les plugins locaux et les outils personnalisés peuvent utiliser des packages npm externes. Ajoutez un package.json à votre répertoire de configuration avec les dépendances dont vous avez besoin.

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

OpenCode exécute bun install au démarrage pour les installer. Vos plugins et outils peuvent ensuite les importer.

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

Structure de base

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


  return {
    // Hook implementations go here
  }
}

La fonction plugin reçoit :

  • project : informations sur le projet actuel.
  • directory : le répertoire de travail actuel.
  • worktree : le chemin de l’arbre de travail git.
  • client : un client SDK opencode pour interagir avec l’IA.
  • $ : shell API de Bun pour l’exécution de commandes.

Prise en charge de TypeScript

Pour les plugins TypeScript, vous pouvez importer des types à partir du package du 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
  }
}

Événements

Les plugins peuvent s’abonner à des événements comme indiqué ci-dessous dans la section Exemples. Voici une liste des différents événements disponibles.

Événements de commande

  • command.executed

Événements de fichier

  • file.edited
  • file.watcher.updated

Événements d’installation

  • installation.updated

LSP Événements

  • lsp.client.diagnostics
  • lsp.updated

Événements de messages

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

Événements d’autorisation

  • permission.asked
  • permission.replied

Événements du serveur

  • server.connected

Événements de session

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

Événements à faire

  • todo.updated

Événements Shell

  • shell.env

Événements d’outils

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

TUI Événements

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

Exemples

Voici quelques exemples de plugins que vous pouvez utiliser pour étendre opencode.

Envoyer des notifications

Envoyez des notifications lorsque certains événements se produisent :

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

Nous utilisons osascript pour exécuter AppleScript sur macOS. Ici, nous l’utilisons pour envoyer des notifications.

Protection .env

Empêchez opencode de lire les fichiers .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")
      }
    },
  }
}

Injecter des variables d’environnement

Injectez des variables d’environnement dans toutes les exécutions du shell (outils d’IA et terminal utilisateur) :

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

Outils personnalisés

Les plugins peuvent également ajouter des outils personnalisés à 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’assistant tool crée un outil personnalisé que opencode peut appeler. Il prend une fonction de schéma Zod et renvoie une définition d’outil avec :

  • description : ce que fait l’outil
  • args : schéma Zod pour les arguments de l’outil
  • execute : Fonction qui s’exécute lorsque l’outil est appelé

Vos outils personnalisés seront disponibles pour opencode aux côtés des outils intégrés.

Enregistrement

Utilisez client.app.log() au lieu de console.log pour la journalisation structurée :

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

Niveaux : debug, info, warn, error. Voir la documentation du SDK pour plus de détails.

Crochets de compactage

Personnalisez le contexte inclus lorsqu’une session est compactée :

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

Le hook experimental.session.compacting se déclenche avant que le LLM ne génère un résumé de continuation. Utilisez-le pour injecter un contexte spécifique au domaine que l’invite de compactage par défaut manquerait.

Vous pouvez également remplacer entièrement l’invite de compactage en définissant 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.
`
    },
  }
}

Lorsque output.prompt est défini, il remplace complètement l’invite de compactage par défaut. Le tableau output.context est ignoré dans ce cas.