# OpenCodeの機能と実践的な使い方
🔌 「完了したら通知してほしい」「.envは絶対に読ませたくない」——そんな要望を数行のTypeScriptで実現。OpenCodeのプラグインは、エージェントの振る舞いをイベントフックで拡張します。
🏷️ タイトル: イベントフック拡張
🔗 URL:
📘 概要
プラグインは、OpenCodeの内部イベントに処理を差し込めるJavaScript/TypeScriptモジュールです。ツール実行の前後、セッションのアイドル、ファイル編集など30以上のイベントにフックして、通知・ロギング・ガード・環境変数注入などを実装できます。プラグイン関数はコンテキストを受け取り、フック実装をまとめたオブジェクトを返します。
⚙️ 機能の説明
・配置場所: プロジェクトは `.opencode/plugins/`、グローバルは `~/.config/opencode/plugins/`。起動時に自動ロードされます。`opencode.json` の `plugin` 配列にnpmパッケージ名を書いて配布することもできます。
・コンテキスト: プラグイン関数は `project`・`client`(SDKクライアント)・`$`(Bunのシェル)・`directory`・`worktree` を受け取ります。
・主なフック: `tool.execute.before` / `tool.execute.after`、`session.idle` / `session.created` / `session.compacted`、`file.edited`、`permission.asked`、`shell.env`、`experimental.session.compacting` など。
・カスタムツール定義やロギング(`
🛠️ 実践的な使い方
完了通知(macOS)と `.env` 読み取り防止の例では、`Plugin` をエクスポートし、`session.idle` フックで `osascript` の通知を出し、`tool.execute.before` フックで `read` 対象が `.env` を含むときに例外を投げて中断します。
環境変数を注入したい場合は `shell.env` フックで ` = "..."` のように設定します。外部パッケージを使うなら `.opencode/package.json` に依存を記述します。
💡 ユースケース
・長時間タスクの完了をデスクトップ通知やSlackへ送り、待ち時間を有効活用する。
・`.env` や鍵ファイルの読取・編集を `tool.execute.before` でブロックし、機密漏洩を防ぐ。
・`experimental.session.compacting` で圧縮プロンプトを差し替え、重要なプロジェクト文脈を要約後も保持する。
⚠️ 注意点
・プラグインで定義したツール名は組み込みツールを上書きします。意図せず標準動作を壊さないよう命名に注意してください。
・ローカルプラグインで外部パッケージを使う場合は `.opencode/package.json` に明示的な依存記述が必要です(npm配布分はBunで自動インストール、キャッシュは `~/.cache/opencode/node_modules/`)。
・`tool.execute.before` で例外を投げるとその操作は中断されます。ガード用途では有効ですが、誤った条件で正常操作まで止めないよう検証してください。
#
OpenCode# #
AIエージェント#