Aller au contenu
OpenCode
HomeDocs

Plugins

Crivez vos propres plugins pour tendre OpenCode.

Les plugins vous permettent d’tendre OpenCode en vous connectant divers vnements et en personnalisant le comportement. Vous pouvez crer des plugins pour ajouter de nouvelles fonctionnalits, intgrer des services externes ou modifier le comportement par dfaut d’OpenCode.

Pour des exemples, consultez les plugins crs par la communaut.

Utiliser un plugin

Il existe deux faons de charger des plugins.

Depuis des fichiers locaux

Placez les fichiers JavaScript ou TypeScript dans le rpertoire des plugins.

  • .opencode/plugin/ - Plugins de niveau projet
  • ~/.config/opencode/plugin/ - Plugins globaux

Les fichiers de ces rpertoires sont chargs automatiquement au dmarrage.

Depuis npm

Spcifiez 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 rguliers et avec porte sont pris en charge.

Parcourez les plugins disponibles dans l’cosystme.

Comment les plugins sont installs

Les plugins npm sont installs automatiquement en utilisant Bun au dmarrage. Les packages et leurs dpendances sont mis en cache dans ~/.cache/opencode/node_modules/.

Les plugins locaux sont chargs directement depuis le rpertoire des plugins. Pour utiliser des packages externes, vous devez crer un package.json dans votre rpertoire de configuration (voir Dpendances), ou publier le plugin sur npm et l’ajouter votre configuration.

Ordre de chargement

Les plugins sont chargs partir de toutes les sources et tous les hooks s’excutent en squence. L’ordre de chargement est :

  1. Configuration globale (~/.config/opencode/opencode.json)
  2. Configuration du projet (opencode.json)
  3. Rpertoire des plugins globaux (~/.config/opencode/plugin/)
  4. Rpertoire des plugins du projet (.opencode/plugin/)

Les packages npm en double avec le mme nom et la mme version sont chargs une seule fois. Cependant, un plugin local et un plugin npm avec des noms similaires sont tous deux chargs sparment.

Crer un plugin

Un plugin est un module JavaScript/TypeScript qui exporte une ou plusieurs fonctions de plugin. Chaque fonction reoit un objet de contexte et renvoie un objet de hooks.

Dpendances

Les plugins locaux et les outils personnaliss peuvent utiliser des packages npm externes. Ajoutez un package.json votre rpertoire de configuration avec les dpendances dont vous avez besoin.

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

OpenCode excute bun install au dmarrage pour installer ces derniers. Vos plugins et outils peuvent ensuite les importer.

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

Structure de base

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


  return {
    // Les implmentations de hooks vont ici
  }
}

La fonction de plugin reoit :

  • project : Les informations du projet actuel.
  • directory : Le rpertoire de travail actuel.
  • worktree : Le chemin de l’arbre de travail git.
  • client : Un client SDK opencode pour interagir avec l’IA.
  • $ : L’API shell de Bun pour excuter des commandes.

Support TypeScript

Pour les plugins TypeScript, vous pouvez importer des types depuis le package de plugin :

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


export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Implmentations de hooks types
  }
}

vnements

Les plugins peuvent s’abonner des vnements comme vu ci-dessous dans la section Exemples. Voici une liste des diffrents vnements disponibles.

vnements de commande

  • command.executed

vnements de fichier

  • file.edited
  • file.watcher.updated

vnements d’installation

  • installation.updated

vnements LSP

  • lsp.client.diagnostics
  • lsp.updated

vnements de message

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

vnements d’autorisation

  • permission.replied
  • permission.updated

vnements de serveur

  • server.connected

vnements de session

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

vnements de todo

  • todo.updated

vnements d’outil

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

vnements TUI

  • 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 vnements se produisent :

.opencode/plugin/notification.js
export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    event: async ({ event }) => {
      // Envoyer une notification  la fin de la session
      if (event.type === "session.idle") {
        await $`osascript -e 'display notification "Session termine !" with title "opencode"'`
      }
    },
  }
}

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

Protection .env

Empchez opencode de lire les fichiers .env :

.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("Ne pas lire les fichiers .env")
      }
    },
  }
}

Outils personnaliss

Les plugins peuvent galement ajouter des outils personnaliss opencode :

.opencode/plugin/custom-tools.ts
import { type Plugin, tool } from "@opencode-ai/plugin"


export const CustomToolsPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      mytool: tool({
        description: "Ceci est un outil personnalis",
        args: {
          foo: tool.schema.string(),
        },
        async execute(args, ctx) {
          return `Bonjour ${args.foo} !`
        },
      }),
    },
  }
}

L’assistant tool cre un outil personnalis qu’opencode peut appeler. Il prend une fonction de schma Zod et renvoie une dfinition d’outil avec :

  • description : Ce que fait l’outil
  • args : Schma Zod pour les arguments de l’outil
  • execute : Fonction qui s’excute lorsque l’outil est appel

Vos outils personnaliss seront disponibles pour opencode aux cts des outils intgrs.

Journalisation

Utilisez client.app.log() au lieu de console.log pour la journalisation structure :

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

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

Hooks de compactage

Personnalisez le contexte inclus lorsqu’une session est compacte :

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


export const CompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Injecter un contexte supplmentaire dans le prompt de compactage
      output.context.push(`
## Contexte personnalis


Incluez tout tat qui doit persister travers le compactage :
- Statut actuel de la tche
- Dcisions importantes prises
- Fichiers en cours de modification
`)
    },
  }
}

Le hook experimental.session.compacting se dclenche avant que le LLM ne gnre un rsum de continuation. Utilisez-le pour injecter un contexte spcifique au domaine que le prompt de compactage par dfaut manquerait.

Vous pouvez galement remplacer entirement le prompt de compactage en dfinissant output.prompt :

.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) => {
      // Remplacer tout le prompt de compactage
      output.prompt = `
Vous gnrez un prompt de continuation pour une session d'essaim multi-agents.


Rsumez :
1. La tche actuelle et son statut
2. Quels fichiers sont modifis et par qui
3. Tous les blocages ou dpendances entre les agents
4. Les prochaines tapes pour terminer le travail


Formatez comme un prompt structur qu'un nouvel agent peut utiliser pour reprendre le travail.
`
    },
  }
}

Lorsque output.prompt est dfini, il remplace entirement le prompt de compactage par dfaut. Le tableau output.context est ignor dans ce cas.