opencode-cc-hooks

A minimal OpenCode plugin that bridges Claude Code hooks to OpenCode's event system.

Write your hooks once in ~/.claude/settings.json — they run in both Claude Code and OpenCode.

Extracted from oh-my-opencode, which provides a full-featured OpenCode plugin with multi-model orchestration, background agents, and more. This project isolates just the Claude Code hooks bridge as a lightweight standalone plugin.

Security notice: Hook commands execute with your user's permissions. Only run hooks you configured yourself. See SECURITY.md for details.

What it does

OpenCode fires events as you work (tool.execute.before, tool.execute.after, chat.message, etc.). This plugin intercepts those events and executes the external commands you've configured in Claude Code's standard hook format, passing the same JSON payloads Claude Code would send.

| Claude Code hook event | Triggered when | |---|---| | PreToolUse | Before a tool (Bash, Edit, Read…) executes | | PostToolUse | After a tool completes | | UserPromptSubmit | When you send a message | | Stop | When the session goes idle (agent finished) | | PreCompact | Before context compaction runs |

Quick start

Install from npm (recommended)

npm install opencode-cc-hooks
# or
bun add opencode-cc-hooks

Then point OpenCode at the installed bundle in ~/.config/opencode/config.json:

{
  "plugin": [
    "/absolute/path/to/node_modules/opencode-cc-hooks/dist/index.js"
  ]
}

Build from source

1. Build

cd opencode-cc-hooks
npm install
npm run build        # → dist/index.js (48kb, no external deps)

2. Register with OpenCode

Add to ~/.config/opencode/config.json:

{
  "plugin": [
    "/absolute/path/to/opencode-cc-hooks/dist/index.js"
  ]
}

Field name is plugin (not plugins).

3. Configure hooks

Hooks are read from the standard Claude Code settings files, merged in order:

| File | Scope | |---|---| | ~/.claude/settings.json | Global (all projects) | | ./.claude/settings.json | Project-level | | ./.claude/settings.local.json | Local override (gitignore this) |

Example ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          { "type": "command", "command": "/path/to/my-guard.sh" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "python3 ~/.claude/hooks/notify.py" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "python3 ~/.claude/hooks/log_activity.py" }
        ]
      }
    ]
  }
}

matcher supports glob patterns (e.g. bash, edit, *) matched against the tool name. Events without a matcher field (like Stop, UserPromptSubmit) match unconditionally.

Hook stdin / stdout protocol

Each hook command receives a JSON object on stdin and may return JSON on stdout.

PreToolUse — block a dangerous command (exit code 2 = deny, 1 = ask, 0 = allow):

// stdin
{ "hook_event_name": "PreToolUse", "tool_name": "bash", "tool_input": { "command": "rm -rf /" }, "session_id": "abc123", "cwd": "/project" }

// stdout to deny
{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Dangerous command" } }

Stop — re-trigger the agent after it finishes:

// stdin
{ "hook_event_name": "Stop", "session_id": "abc123", "cwd": "/project", "stop_hook_active": false }

// stdout to re-trigger
{ "decision": "block", "inject_prompt": "You forgot to run the tests." }

For the full payload schema of all 5 events (PostToolUse, UserPromptSubmit, PreCompact, …) see docs/hook-protocol.md.

Selectively disabling hooks

Create ~/.config/opencode/opencode-cc-plugin.json (global) or .opencode/opencode-cc-plugin.json (project) to disable specific hook commands by regex pattern:

{
  "disabledHooks": {
    "PostToolUse": ["log_activity\\.py"],
    "Stop": ["notify\\.py"]
  }
}

Patterns are matched against the full command string.

Development

npm run build          # one-shot build
npm run build:watch    # rebuild on file change

Output is always dist/index.js — restart OpenCode after each build to pick up changes.

Project structure

src/
├── index.ts                          # Plugin entry point (9 lines)
├── hooks/
│   └── claude-code-hooks/
│       ├── claude-code-hooks-hook.ts # Assembles the 5 event handlers
│       ├── config.ts                 # Reads ~/.claude/settings.json
│       ├── config-loader.ts          # Reads opencode-cc-plugin.json
│       ├── types.ts                  # All TypeScript types
│       ├── pre-tool-use.ts           # PreToolUse executor
│       ├── post-tool-use.ts          # PostToolUse executor
│       ├── user-prompt-submit.ts     # UserPromptSubmit executor
│       ├── stop.ts                   # Stop executor
│       ├── pre-compact.ts            # PreCompact executor
│       ├── transcript.ts             # Session transcript builder
│       └── handlers/                 # OpenCode event → hook executor bridge
└── shared/                           # Minimal utility functions (no heavy deps)
    ├── command-executor/             # Spawns hook commands as child processes
    ├── pattern-matcher.ts            # Glob/regex matcher for tool names
    └── ...

Requirements

• OpenCode with plugin support
• Node.js ≥ 18 (for npm install / npm run build)
• Bun runtime (OpenCode runs plugins in Bun)
• esbuild (installed as devDependency)