---
title: プラグイン
description: OpenCode を拡張する独自のプラグインを作成します。
---

プラグインを使用すると、さまざまなイベントにフックして動作をカスタマイズすることで OpenCode を拡張できます。プラグインを作成して、新しい機能を追加したり、外部サービスと統合したり、OpenCode のデフォルトの動作を変更したりできます。

たとえば、コミュニティによって作成された [plugins](/docs/ecosystem#plugins) をチェックしてください。

---

## プラグインを使用する

プラグインをロードするには 2 つの方法があります。

---

### ローカルファイルから

JavaScript または TypeScript ファイルをプラグイン ディレクトリに配置します。

- `.opencode/plugins/` - プロジェクトレベルのプラグイン
- `~/.config/opencode/plugins/` - グローバルプラグイン

これらのディレクトリ内のファイルは起動時に自動的にロードされます。

---

### npmから

構成ファイルで npm パッケージを指定します。

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

通常の npm パッケージとスコープ指定された npm パッケージの両方がサポートされています。

[ecosystem](/docs/ecosystem#plugins).

---

### プラグインのインストール方法

**npm プラグイン** は、起動時に Bun を使用して自動的にインストールされます。パッケージとその依存関係は `~/.cache/opencode/node_modules/` にキャッシュされます。

**ローカル プラグイン**は、プラグイン ディレクトリから直接ロードされます。外部パッケージを使用するには、config ディレクトリ内に `package.json` を作成するか ([Dependency](#dependencies) を参照)、プラグインを npm に公開して [config](/docs/config#plugins) に追加する] 必要があります。

---

### ロード順序

プラグインはすべてのソースからロードされ、すべてのフックが順番に実行されます。ロード順序は次のとおりです。

1. グローバル構成 (`~/.config/opencode/opencode.json`)
2. プロジェクト構成 (`opencode.json`)
3. グローバルプラグインディレクトリ (`~/.config/opencode/plugins/`)
4. プロジェクトプラグインディレクトリ (`.opencode/plugins/`)

同じ名前とバージョンを持つ重複した npm パッケージは 1 回ロードされます。ただし、似た名前のローカル プラグインと npm プラグインは両方とも別々にロードされます。

---

## プラグインを作成する

プラグインは、1 つ以上のプラグインをエクスポートする **JavaScript/TypeScript モジュール**です
機能。各関数はコンテキスト オブジェクトを受け取り、フック オブジェクトを返します。

---

### 依存関係

ローカル プラグインとカスタム ツールは外部の npm パッケージを使用できます。必要な依存関係を含む `package.json` を config ディレクトリに追加します。

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

OpenCode は起動時に `bun install` を実行してこれらをインストールします。プラグインとツールはそれらをインポートできるようになります。

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

---

### 基本構造

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

  return {
    // Hook implementations go here
  }
}
```

プラグイン関数は以下を受け取ります。

- `project`: 現在のプロジェクト情報。
- `directory`: 現在の作業ディレクトリ。
- `worktree`: git ワークツリーのパス。
- `client`: AI と対話するためのopencode SDK クライアント。
- `$`: Bun の [コマンドを実行するためのshell API](https://bun.com/docs/runtime/shell)。

---

### TypeScript のサポート

TypeScript プラグインの場合、プラグイン パッケージから型をインポートできます。

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

---

### イベント

以下の「例」セクションに示すように、プラグインはイベントをサブスクライブできます。利用可能なさまざまなイベントのリストは次のとおりです。

#### コマンドイベント

- `command.executed`

#### ファイルイベント

- `file.edited`
- `file.watcher.updated`

#### インストールイベント

- `installation.updated`

#### LSPイベント

- `lsp.client.diagnostics`
- `lsp.updated`

#### メッセージイベント

- `message.part.removed`
- `message.part.updated`
- `message.removed`
- `message.updated`

#### 許可イベント

- `permission.asked`
- `permission.replied`

#### サーバーイベント

- `server.connected`

#### セッションイベント

- `session.created`
- `session.compacted`
- `session.deleted`
- `session.diff`
- `session.error`
- `session.idle`
- `session.status`
- `session.updated`

#### Todoイベント

- `todo.updated`

#### shellイベント

- `shell.env`

#### ツールイベント

- `tool.execute.after`
- `tool.execute.before`

#### TUIイベント

- `tui.prompt.append`
- `tui.command.execute`
- `tui.toast.show`

---

## 例

ここでは、opencodeを拡張するために使用できるプラグインの例をいくつか示します。

---

### 通知を送信する

特定のイベントが発生したときに通知を送信します。

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

macOS 上で AppleScript を実行するために `osascript` を使用しています。ここでは通知を送信するために使用しています。

:::note
OpenCode デスクトップ アプリを使用している場合は、応答の準備ができたとき、またはセッション エラーが発生したときにシステム通知を自動的に送信できます。
:::

---

### .env 保護

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

---

### 環境変数を挿入する

すべてのshell 実行 (AI ツールとユーザーterminal) に環境変数を挿入します。

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

---

### カスタムツール

プラグインは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})`
        },
      }),
    },
  }
}
```

`tool` ヘルパーは、opencode が呼び出すことができるカスタム ツールを作成します。 Zod スキーマ関数を受け取り、次のようなツール定義を返します。

- `description`: ツールの機能
- `args`: ツールの引数の Zod スキーマ
- `execute`: ツールが呼び出されたときに実行される関数

カスタム ツールは、組み込みツールと並行してopencodeに使用できます。

---

### ロギング

構造化ログには `console.log` の代わりに `client.app.log()` を使用します。

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

レベル: `debug`、`info`、`warn`、`error`。詳細については、[SDK ドキュメント](https://opencode.ai/docs/sdk) を参照してください。

---

### 圧縮フック

セッションが圧縮されたときに含まれるコンテキストをカスタマイズします。

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

`experimental.session.compacting` フックは、LLM が継続概要を生成する前に起動します。これを使用して、デフォルトの圧縮プロンプトでは見逃されるドメイン固有のコンテキストを挿入します。

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

`output.prompt` を設定すると、デフォルトの圧縮プロンプトが完全に置き換えられます。この場合、`output.context` 配列は無視されます。