OpenAgentsControl/.opencode/context/openagents-repo/concepts/hooks-system.md

Hooks System

Purpose: User-defined shell commands that execute at Claude Code lifecycle points

---

Core Concept

Hooks provide deterministic control over Claude Code's behavior. Unlike prompting (which suggests), hooks guarantee certain actions happen at specific points in the workflow.

---

Key Points

• Hooks are shell commands triggered by events
• Run automatically during agent loop with your credentials
• Can block operations (exit code 2), allow silently, or provide feedback
• Configure in settings.json or plugin's hooks/hooks.json
• Matchers filter which tools/events trigger the hook

---

Common Use Cases

Use Case	Event	Example
Auto-format	PostToolUse	Run prettier after Edit/Write
Notifications	Notification	Desktop alert when input needed
File protection	PreToolUse	Block edits to .env files
Logging	PreToolUse	Track all bash commands
Feedback	PostToolUse	Lint check after code changes

---

Quick Example

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
      }]
    }]
  }
}

---

Security Warning

Hooks run with your credentials. Malicious hooks can exfiltrate data. Always review hook implementations before adding them.

---

Related

• ../lookup/hook-events.md - All hook events
• ../examples/hooks/ - Hook examples

Reference: https://docs.anthropic.com/en/docs/claude-code/hooks