opencode/packages/web/src/content/docs/fr/plugins.mdx

---
title: Plugins
description: É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](/docs/ecosystem#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.

---

### Depuis npm

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

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

Les packages npm scopés et standards sont pris en charge.

Parcourez les plugins disponibles dans le [ecosystem](/docs/ecosystem#plugins).

---

### 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](#dependencies)), ou publier le plugin sur npm et [l'ajouter à votre config](/docs/config#plugins).

---

### 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 une ou plusieurs fonctions de plugin. 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.

```json title=".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.

```ts title=".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

```js title=".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](https://bun.com/docs/runtime/shell) 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 :

```ts title="my-plugin.ts" {1}
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 :

```js title=".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.

:::note
Si vous utilisez l'application de bureau OpenCode, elle peut envoyer automatiquement des notifications système lorsqu'une réponse est prête ou en cas d'erreur de session.
:::

---

### Protection .env

Empêchez opencode de lire les fichiers `.env` :

```javascript title=".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) :

```javascript title=".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 :

```ts title=".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.

---

### Journalisation

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

```ts title=".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](https://opencode.ai/docs/sdk) pour plus de détails.

---

### Hooks de compactage

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

```ts title=".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 le prompt de compactage par défaut manquerait.

Vous pouvez également remplacer entièrement le prompt de compactage en définissant `output.prompt` :

```ts title=".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 le prompt de compactage par défaut. Le tableau `output.context` est ignoré dans ce cas.