Skip to content

Hooks Configuration

Jump to bottom
Mo Abualruz edited this page Dec 5, 2025 · 1 revision

Hooks Configuration Guide

Status: ✅ Complete

Last Updated: December 5, 2025

Overview

This guide covers how to configure hooks in ricecoder. Hooks are defined in YAML configuration files and support a wide range of customization options.

Configuration File Location

Hooks are configured in .ricecoder/hooks.yaml in your project directory:

my-project/
├── .ricecoder/
│   └── hooks.yaml          # Project-level hooks
├── src/
└── README.md

User-level hooks can be configured in ~/.ricecoder/hooks.yaml.

Configuration Hierarchy

Hooks are loaded from multiple sources in priority order:

  1. Runtime: Configuration passed programmatically (highest priority)
  2. Project: .ricecoder/hooks.yaml (project-specific)
  3. User: ~/.ricecoder/hooks.yaml (user-level)
  4. Built-in: Built-in hook templates and defaults (lowest priority)

Later sources override earlier ones. For example, a project-level hook with the same name as a user-level hook will override it.

Basic Configuration

Minimal Hook

hooks:
  - name: "My Hook"
    event: "file_modified"
    action:
      type: "command"
      command: "echo"
      args:
        - "File changed"

Complete Hook

hooks:
  - name: "Format on save"
    description: "Automatically format files when saved"
    event: "file_modified"
    action:
      type: "command"
      command: "prettier"
      args:
        - "--write"
        - "{{file_path}}"
      timeout_ms: 5000
      capture_output: true
    enabled: true
    tags:
      - "formatting"
      - "auto"
    metadata:
      author: "team"
      version: "1.0"
    condition:
      expression: "file_path.endsWith('.ts')"

Hook Properties

name (required)

Human-readable hook name. Used for display and identification.

name: "Format on save"

description (optional)

Hook description explaining what it does.

description: "Automatically format TypeScript files when saved"

event (required)

Event type that triggers the hook. See Hooks Events Guide for available events.

event: "file_modified"

action (required)

Action to execute when hook is triggered. See Hooks Actions Guide for action types.

action:
  type: "command"
  command: "prettier"
  args:
    - "{{file_path}}"

enabled (optional)

Whether the hook is active. Default: true.

enabled: true

tags (optional)

Tags for organizing and filtering hooks.

tags:
  - "formatting"
  - "auto"
  - "typescript"

metadata (optional)

Custom metadata for the hook.

metadata:
  author: "team"
  version: "1.0"
  priority: "high"

condition (optional)

Condition that must be met to execute the hook. If not specified, hook always executes.

condition:
  expression: "file_path.endsWith('.ts')"

Action Types

Command Action

Execute a shell command:

action:
  type: "command"
  command: "prettier"
  args:
    - "--write"
    - "{{file_path}}"
  timeout_ms: 5000
  capture_output: true

Properties:

  • command (required): Command to execute
  • args (optional): Command arguments (supports variable substitution)
  • timeout_ms (optional): Timeout in milliseconds (default: 30000)
  • capture_output (optional): Capture command output (default: true)

Tool Call Action

Call a ricecoder tool with parameter binding:

action:
  type: "tool_call"
  tool_name: "code_formatter"
  tool_path: "/usr/local/bin/prettier"
  parameters:
    file_path: "{{file_path}}"
    output_dir: "/tmp/formatted"
    style: "prettier"
  timeout_ms: 10000

Properties:

  • tool_name (required): Name of the tool
  • tool_path (required): Path to tool executable or handler
  • parameters (optional): Tool parameters (supports variable substitution)
  • timeout_ms (optional): Timeout in milliseconds (default: 30000)

AI Prompt Action

Send a prompt to an AI assistant:

action:
  type: "ai_prompt"
  prompt_template: |
    Review this code change:
    File: {{file_path}}
    
    Provide feedback.
  model: "gpt-4"
  temperature: 0.7
  max_tokens: 2000
  stream: true

Properties:

  • prompt_template (required): Prompt template (supports variable substitution)
  • model (optional): AI model to use (default: configured default)
  • temperature (optional): Temperature for AI response (0.0-1.0, default: 0.7)
  • max_tokens (optional): Maximum tokens in response (default: 2000)
  • stream (optional): Stream response (default: false)

Chain Action

Execute multiple hooks in sequence:

action:
  type: "chain"
  hook_ids:
    - "format-hook-id"
    - "lint-hook-id"
    - "test-hook-id"
  pass_output: true

Properties:

  • hook_ids (required): List of hook IDs to execute in sequence
  • pass_output (optional): Pass previous hook output as context (default: false)

Variable Substitution

Variables are substituted in command arguments, tool parameters, and AI prompts. Use {{variable_name}} syntax:

action:
  type: "command"
  command: "echo"
  args:
    - "File: {{file_path}}"
    - "Size: {{file_size}}"

Available variables depend on the event type. See Hooks Variables Guide for complete reference.

Nested Variables

Access nested properties with dot notation:

args:
  - "{{metadata.size}}"
  - "{{context.user_id}}"

Literal Values

Mix literal values with variables:

args:
  - "{{file_path}}/subdir"
  - "output-{{timestamp}}.txt"

Conditions

Execute hooks only when conditions are met:

condition:
  expression: "file_path.endsWith('.ts')"

Conditions are evaluated against the event context. If the condition evaluates to false, the hook is skipped.

Common Conditions

# Only TypeScript files
condition:
  expression: "file_path.endsWith('.ts')"

# Only in src directory
condition:
  expression: "file_path.includes('/src/')"

# Only modified (not created)
condition:
  expression: "operation_type == 'modified'"

# Only large files
condition:
  expression: "file_size > 1000000"

Hook Templates

Built-in templates for common patterns:

File Save Hook

hooks:
  - name: "Format on save"
    event: "file_modified"
    action:
      type: "command"
      command: "prettier"
      args:
        - "--write"
        - "{{file_path}}"

Git Hook

hooks:
  - name: "Pre-commit checks"
    event: "git_pre_commit"
    action:
      type: "command"
      command: "npm"
      args:
        - "run"
        - "lint"

Build Hook

hooks:
  - name: "Post-build cleanup"
    event: "build_complete"
    action:
      type: "command"
      command: "rm"
      args:
        - "-rf"
        - "dist/temp"

Examples

Example 1: Format TypeScript Files

hooks:
  - name: "Format TypeScript"
    event: "file_modified"
    condition:
      expression: "file_path.endsWith('.ts')"
    action:
      type: "command"
      command: "prettier"
      args:
        - "--write"
        - "{{file_path}}"
    enabled: true

Example 2: Run Tests on Save

hooks:
  - name: "Run tests"
    event: "file_modified"
    condition:
      expression: "file_path.includes('/src/')"
    action:
      type: "command"
      command: "npm"
      args:
        - "test"
        - "--"
        - "{{file_path}}"
    enabled: true

Example 3: AI Code Review

hooks:
  - name: "AI review"
    event: "file_modified"
    action:
      type: "ai_prompt"
      prompt_template: |
        Review this code change:
        File: {{file_path}}
        Old hash: {{old_hash}}
        New hash: {{new_hash}}
        
        Provide feedback on the changes.
      model: "gpt-4"
      temperature: 0.7
      stream: true
    enabled: true

Example 4: Tool Integration

hooks:
  - name: "Custom formatter"
    event: "file_modified"
    action:
      type: "tool_call"
      tool_name: "custom_formatter"
      tool_path: "./tools/formatter"
      parameters:
        file_path: "{{file_path}}"
        style: "prettier"
        output_dir: "/tmp/formatted"
    enabled: true

Example 5: Hook Chain

hooks:
  - name: "Format and lint"
    event: "file_modified"
    action:
      type: "chain"
      hook_ids:
        - "format-hook"
        - "lint-hook"
      pass_output: true
    enabled: true

Configuration Validation

Hooks configuration is validated when loaded. Invalid configuration will be rejected with clear error messages.

Common Validation Errors

Missing required field:

Error: Hook "My Hook" is missing required field: event

Invalid event type:

Error: Hook "My Hook" has invalid event type: "unknown_event"

Invalid action type:

Error: Hook "My Hook" has invalid action type: "unknown_action"

Invalid condition:

Error: Hook "My Hook" has invalid condition expression

Hot-Reload

Configuration changes are automatically detected and reloaded without restart. When you modify .ricecoder/hooks.yaml:

  1. File watcher detects change
  2. Configuration is reloaded
  3. Hooks are updated
  4. Hook state (enabled/disabled) is preserved

If configuration is invalid, the previous configuration is kept and an error is logged.

Troubleshooting

Configuration Not Loading

Problem: Hooks are not loading from configuration file.

Solutions:

  1. Verify file path: .ricecoder/hooks.yaml
  2. Check file permissions (must be readable)
  3. Verify YAML syntax is correct
  4. Check logs for configuration errors

Variables Not Substituting

Problem: Variables like {{file_path}} are not being replaced.

Solutions:

  1. Verify variable name is correct (case-sensitive)
  2. Check event type provides the variable
  3. Use ricecoder hooks inspect to see available variables
  4. See Hooks Variables Guide for reference

Hook Not Executing

Problem: Hook is configured but not executing.

Solutions:

  1. Verify hook is enabled: ricecoder hooks inspect <hook-id>
  2. Check event name matches exactly
  3. Verify condition expression is correct
  4. Check hook configuration syntax

See Also

Last updated: December 5, 2025

Clone this wiki locally