# Hooks Guide

Learn how to customize and extend CodeBuddy Code's behavior by registering shell commands

> We recommend reading the [Hook Reference Guide](./hooks.md) first to understand all events, input/output structures, and security requirements. This guide focuses on practical walkthroughs and common examples to help you quickly enable Hooks functionality in your CodeBuddy Code projects.
> **Note**: The Hooks feature is currently in **Beta** and is being actively refined. Please watch for updates in future releases.

name: code-reviewer
description: Code review Skill that checks the Bash command whitelist before execution
context: fork
agent: Explore
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: ${CODEBUDDY_SKILL_DIR}/scripts/check-bash.sh
          timeout: 5
  Stop:  # Automatically rewritten as SubagentStop
    - hooks:
        - type: command
          command: echo "review done at $(date)" >> ${CODEBUDDY_PROJECT_DIR}/.cbc-review.log
---

Please review the code involved in $ARGUMENTS...
```

**Before enabling**: Open the gate in `~/.codebuddy/settings.json` (off by default; all frontmatter hooks from non-built-in sources are silently skipped):

```json
{
  "allowUntrustedFrontmatterHooks": true
}
```

For more detailed field semantics, security gates, and scope rules, see [Skills Documentation - Configuring Hooks in Skills](./skills.md#configuring-hooks-in-skills) and [Hook Reference Guide - Frontmatter Hooks](./hooks.md#agent--skill-frontmatter-hooks).

## Best Practices and Recommendations

1. **Validate incrementally**: Start with logging hooks before gradually adding high-risk operations.
2. **Control timeouts**: Default is 60 seconds; if your script has long-running tasks, ensure timely output or split processing.
3. **Use matcher filtering**: Properly setting `matcher` can reduce unnecessary hook executions.
4. **Centralize script directory**: Recommend creating a `.codebuddy/hooks/` directory in the project root to centrally manage scripts and include them in version control.
5. **Prioritize security**:
   * Avoid using unvalidated user input directly in hooks.
   * Use absolute paths for external commands to prevent PATH hijacking.
   * Combine with the `/hooks` panel's security confirmation mechanism to ensure all hooks are reviewed before running.
6. **Work with MCP tools**: MCP tool names follow the pattern `mcp__<server>__<tool>` and can be batch-controlled in `matcher` using regex, e.g., `mcp__github__.*`.
7. **The panel is the authoritative entry point**: Any external file modifications need to be confirmed in the panel before taking effect; be sure to complete this step.
8. **Python script invocation**: Always use `python3 your_script.py` instead of directly executing `.py` files, because the Windows Git Bash environment may not correctly recognize the shebang line of Python scripts.
9. **Windows compatibility**: Hook commands are executed via Git Bash on Windows. Ensure commands use bash syntax and avoid relying on cmd.exe or PowerShell-specific syntax.

## Learn More

* For reference documentation on hooks, see the [Hook Reference Guide](./hooks.md).
* For comprehensive security best practices and safety guidelines, see [Security Considerations](./hooks.md#security-notes) in the Hook Reference Guide.
* For troubleshooting steps and debugging techniques, see the [Debugging](./hooks.md#debugging) section in the Hook Reference Guide.

---

Now you've mastered the core workflow for enabling hooks in CodeBuddy Code. For more details on event fields, decision control, and security considerations, check out the [Hook Reference Guide](./hooks.md). Happy building powerful and secure automated workflows!
