Automated Hooks Engine

Relevant source files

The following files were used as context for generating this wiki page:

• hooks/hooks.json
• hooks/README.md
• AGENTS.md
• rules/web/hooks.md
• CONTRIBUTING.md

The Automated Hooks Engine is an event-driven automation system within the Everything Claude Code (ECC) project. Its primary purpose is to intercept Claude Code tool executions to enforce quality standards, prevent common mistakes, and automate repetitive development tasks such as linting, formatting, and type-checking.

By integrating directly with the AI's tool-calling lifecycle, the engine ensures that security checks, architectural guardrails, and environment validations occur transparently without requiring explicit user intervention. This provides a "safety net" for AI-driven development, ensuring that code generated or modified by agents adheres to project-specific standards before being committed or executed.

Sources: hooks/README.md:1-5, AGENTS.md:1-5

Architecture and Lifecycle

The engine operates on a lifecycle that wraps tool calls into several distinct stages. Each stage allows for specialized logic to be executed based on the current tool and its intended input or resulting output.

Execution Flow

The standard lifecycle of a tool call under the Hooks Engine follows a sequential path:

The flow shows how hooks wrap around the tool execution to provide validation (Pre) and analysis (Post).
Sources: hooks/README.md:7-12, CONTRIBUTING.md:183-195

Hook Types and Triggers

The engine supports several hook types, each triggered at specific points in the session or tool lifecycle:

Type	Trigger Event	Primary Use Case
PreToolUse	Before a tool (e.g., Bash, Write) runs	Validation, safety blocks, or warnings.
PostToolUse	After a tool completes its run	Formatting, automated checks, or notifications.
Stop	After each AI assistant response	Persistence, cleanup, or status audits.
SessionStart	When the Claude Code session begins	Context loading and environment detection.
SessionEnd	When the session terminates	Lifecycle markers and resource cleanup.
PreCompact	Before context window compaction	State preservation.

Sources: hooks/README.md:14-25, CONTRIBUTING.md:183-195

Component Logic and Data Handling

Hooks are implemented as standalone commands (often Node.js scripts) that interact with the engine via standard I/O and exit codes.

Input Data Structure

Every hook receives a JSON object on stdin containing the context of the current operation.

interface HookInput {
  tool_name: string;          // e.g., "Bash", "Edit", "Write"
  tool_input: {
    command?: string;         // For Bash tools
    file_path?: string;       // For file operations
    content?: string;         // For Write operations
    old_string?: string;      // For Edit operations
    new_string?: string;      // For Edit operations
  };
  tool_output?: {             // PostToolUse hooks only
    output?: string;          // The actual tool result
  };
}

Sources: hooks/README.md:162-178

Execution Logic and Exit Codes

The behavior of a PreToolUse hook is determined by its exit code:

• 0 (Success): Execution continues normally. Warnings can be sent via stderr without stopping the tool.
• 2 (Block): The tool call is aborted. This is used for critical safety or quality violations (e.g., blocking a file that exceeds 800 lines).
• Other Non-Zero: Logged as an error but typically does not block the core flow.

Sources: hooks/README.md:155-160, rules/web/hooks.md:55-72

Core Hook Implementations

The project includes several pre-configured hooks that enforce standard development workflows.

Safety and Security Guardrails

The engine implements strict blocks for dangerous operations and non-standard project structures.

• Dev Server Blocker: Blocks execution of development servers (like npm run dev) if they are started outside of a terminal multiplexer like tmux.
• Doc File Warning: Prevents the creation of non-standard .md or .txt files outside of approved directories like docs/ or skills/.
• File Size Guard: A PreToolUse hook for the Write tool that blocks any attempt to create a file exceeding 800 lines to maintain modularity.

Sources: hooks/README.md:36-47, rules/web/hooks.md:55-72

Automated Quality Gates

Post-modification hooks ensure code remains valid after AI edits.

• Format on Save: Automatically runs prettier --write after the Edit or Write tools modify frontend files.
• Incremental Type Check: Runs tsc --noEmit with the --incremental flag after edits. It includes a timeout (e.g., 60 seconds) to prevent stale processes from accumulating.
• Linting: Executes eslint --fix on modified files to resolve stylistic issues immediately.

Sources: rules/web/hooks.md:8-42

Hook Configuration Example

Hooks are defined in a hooks.json file using a matcher syntax that identifies the target tool and specific patterns in the input.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "tool == \"Bash\" && tool_input.command matches \"git push\"",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Hook] Review changes before pushing'"
          }
        ],
        "description": "Reminder to review before push"
      }
    ]
  }
}

Sources: CONTRIBUTING.md:204-220

Configuration and Environment Controls

Users can tune the behavior of the Hooks Engine using environment variables, allowing for different levels of strictness without modifying the underlying configuration files.

Variable	Description	Options
ECC_HOOK_PROFILE	Sets the overall strictness level	minimal, standard, strict
ECC_DISABLED_HOOKS	Disables specific hooks by ID	Comma-separated list of IDs
ECC_GATEGUARD	Toggles primary quality gate hooks	on, off

Sources: hooks/README.md:88-106

Summary

The Automated Hooks Engine acts as a programmatic governance layer for AI-assisted development. By wrapping tool calls in a structured lifecycle of validations and automated corrections, it ensures that project-specific rules regarding file size, security, formatting, and type-safety are followed automatically. This modular architecture allows developers to easily extend the system with new scripts that target specific tools and events within the Claude Code environment.

Sources: hooks/README.md:1-25, CONTRIBUTING.md:183-195