Quick answer
opencode hooks: what to know first
Hooks は実行タイミングが重要な時だけ使います。ツール前後の小さなガードレールであり、skills、commands、MCP、権限、CI の代替ではありません。
Hooks は実行タイミングが重要な時だけ使います。ツール前後の小さなガードレールであり、skills、commands、MCP、権限、CI の代替ではありません。
This page deliberately separates `opencode hooks` from the site's broader OpenCode Plugins guide. The plugins page explains when packaged extensions are worth installing. This page focuses on lifecycle behavior: event choice, scope, placement, examples, failure modes, testing, rollback, and how hooks interact with tools, skills, commands, MCP, and GitHub automation.
Related site guides: OpenCode Plugins, OpenCode Skills, OpenCode MCP, OpenCode session storage.
1. hooks を使う場面
Hooks は実行タイミングが重要な時だけ使います。ツール前後の小さなガードレールであり、skills、commands、MCP、権限、CI の代替ではありません。
正確なタイミングに依存しないなら、skill、command、permission、MCP に置く方が安全です。Hook には明確な条件と見える結果が必要です。
2. hooks の配置場所
Hooks は実行タイミングが重要な時だけ使います。ツール前後の小さなガードレールであり、skills、commands、MCP、権限、CI の代替ではありません。
リポジトリ規則は project 側に置き、チームがレビューできるようにします。個人設定は global、npm package は source と version の確認が前提です。
3. イベントを選ぶ
Hooks は実行タイミングが重要な時だけ使います。ツール前後の小さなガードレールであり、skills、commands、MCP、権限、CI の代替ではありません。
まずイベントを一文で書きます。実行前、tool 後、file 変更後のどれかを明確にし、複数の行動が混ざるなら hook を分けます。
4. 安全例とリスク
Hooks は実行タイミングが重要な時だけ使います。ツール前後の小さなガードレールであり、skills、commands、MCP、権限、CI の代替ではありません。
安全な例は警告、正規化、最小限の記録です。commit、push、secret、遠隔 network、無言の大きな編集は hook に隠さないでください。
5. 使い捨てリポジトリでテスト
Hooks は実行タイミングが重要な時だけ使います。ツール前後の小さなガードレールであり、skills、commands、MCP、権限、CI の代替ではありません。
小さな repo、無害な command、出力確認、plugin を無効化する手順まで含めてテストします。
6. レイヤー別に切り分ける
Hooks は実行タイミングが重要な時だけ使います。ツール前後の小さなガードレールであり、skills、commands、MCP、権限、CI の代替ではありません。
問題が出たら一層ずつ無効化し、同じ task を繰り返します。Lifecycle code、instructions、MCP、provider を切り分けられます。
7. GitHub と CI から分ける
Hooks は実行タイミングが重要な時だけ使います。ツール前後の小さなガードレールであり、skills、commands、MCP、権限、CI の代替ではありません。
GitHub と CI は明示的な workflow に置きます。Local hooks は session 中の guardrail に限定します。
OpenCode hooks FAQ
OpenCode hooks とは？
plugins が返すライフサイクル callback です。
plugins と同じですか？
違います。plugin が hooks を読み込み返します。
どこに置きますか？
リポジトリ規則は project、個人設定は global に置きます。
権限の代替ですか？
いいえ。広い policy は permissions で扱います。
どうテストしますか？
使い捨て repo で小さな task と rollback を確認します。
Sources
Official OpenCode documentation and current SERP evidence were checked on 2026-07-23. Plugin APIs and event names can change, so verify exact code against the current docs before shipping a hook.