A TypeScript plugin system for OpenCode AI that provides event-driven hooks for session lifecycle, tool execution, file operations, and UI notifications (toasts).
- 28 OpenCode Events — Full coverage of all documented OpenCode events: session, message, tool, file, permission, server, command, LSP, installation, todo, shell, TUI, and experimental events
- Toast Notifications — Staggered, non-overlapping toasts with configurable title, variant, message, and duration
- Script Execution — Run shell scripts on any event with per-event and per-tool configuration
- File Persistence — Save script output and event logs to disk
- Session Context — Append script output to the active OpenCode session
- Type-Safe Configuration — Full TypeScript support with autocomplete and compile-time validation
- Per-Tool Configuration — Different behavior for different tools (e.g.,
task,chat,git.commit)
- OpenCode AI installed
- Node.js 18+
Add the plugin to your opencode.json:
{
"plugins": ["@johnatas-henrique/opencode-hooks@latest"]
}OpenCode installs and loads the plugin automatically.
npm install @johnatas-henrique/opencode-hooksCreate the entry point .opencode/plugins/opencode-hooks.ts:
export { default } from '@johnatas-henrique/opencode-hooks';OpenCode detects and loads the plugin from this file.
mkdir -p .opencode/plugins
cd .opencode/plugins
git clone <repository-url> opencode-hooks
cd opencode-hooks
npm install
npm run buildZero configuration required. When OpenCode starts with the plugin:
- Claude hooks detected — existing hooks from
~/.claude/hooks/and.claude/hooks/are loaded and mapped to OpenCode events automatically - Default config created —
.opencode/opencode-hooks.jsoncis created with sensible defaults if no config exists - Status toast — a notification shows which plugins are active
- Scripts directory —
.opencode/scripts/is created for your custom scripts - Audit logging — event logs start recording under
opencode-hooks/logs/
Everything works out of the box. To customize behavior, edit .opencode/opencode-hooks.jsonc — see Configuration.
- See Configuration to customize events, tools, scripts, and audit via JSONC
- See Scripts to learn how to write blocking scripts, async scripts, and Claude-compatible hooks
- See Events for the full event catalog with available fields
| Document | Description |
|---|---|
| Configuration | Full reference for opencode-hooks.jsonc — all config fields, types, events, tools, audit, and toasts |
| Scripts | How to write and run shell scripts — stdin formats, blocking, async, exit codes, Claude Code compatibility |
| Events | Event catalog with available fields, descriptions, and recommended toast fields |
| Claude Code Compatibility | How Claude Code .sh hooks map to OpenCode events — stdin field comparison, limitations, and migration checklist |
| Audit System | Audit logging reference — log files, sanitization, archiving, and migration |
npm run build # Compile TypeScript
npm run test:unit # Run unit tests
npm run test:cov # Run tests with coverage
npm run test:integration # Run integration tests
npm run test:e2e # Run E2E tests
npm run test:all # Run all tests (unit + integration + e2e)
npm run coverage:report # Full coverage report (HTML)
npm run lint # Run ESLint
npm run lint:fix # Fix ESLint errors
npm run format # Run Prettier
npm run format:check # Check formattingCurrent coverage: 99%+ statements, 99%+ branches, 99%+ functions, 99%+ lines
npm run test:cov # Terminal coverage summary
npm run coverage:report # HTML report in coverage/lcov-report/index.htmlMIT