Skip to content

Hooks Events

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

Hooks Events Guide

Status: ✅ Complete

Last Updated: December 5, 2025

Overview

This guide documents all available events that can trigger hooks in ricecoder. Events are emitted when specific system actions occur, and hooks registered for those events will be triggered automatically.

File Operation Events

File operation events are emitted when files are created, modified, deleted, renamed, or moved.

file_created

Emitted when a file is created.

Event Context:

{
  "file_path": "/path/to/file.ts",
  "size": 1024,
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "New file created"
    event: "file_created"
    action:
      type: "command"
      command: "echo"
      args:
        - "New file: {{file_path}}"

file_modified

Emitted when a file is modified.

Event Context:

{
  "file_path": "/path/to/file.ts",
  "old_hash": "abc123def456",
  "new_hash": "def456ghi789",
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "File modified"
    event: "file_modified"
    action:
      type: "command"
      command: "prettier"
      args:
        - "--write"
        - "{{file_path}}"

file_deleted

Emitted when a file is deleted.

Event Context:

{
  "file_path": "/path/to/file.ts",
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "File deleted"
    event: "file_deleted"
    action:
      type: "command"
      command: "echo"
      args:
        - "File deleted: {{file_path}}"

file_renamed

Emitted when a file is renamed.

Event Context:

{
  "old_path": "/path/to/old_name.ts",
  "new_path": "/path/to/new_name.ts",
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "File renamed"
    event: "file_renamed"
    action:
      type: "command"
      command: "echo"
      args:
        - "Renamed: {{old_path}} -> {{new_path}}"

file_moved

Emitted when a file is moved to a different directory.

Event Context:

{
  "old_path": "/path/to/old/file.ts",
  "new_path": "/path/to/new/file.ts",
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "File moved"
    event: "file_moved"
    action:
      type: "command"
      command: "echo"
      args:
        - "Moved: {{old_path}} -> {{new_path}}"

file_read

Emitted when a file is read.

Event Context:

{
  "file_path": "/path/to/file.ts",
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "File read"
    event: "file_read"
    action:
      type: "command"
      command: "echo"
      args:
        - "File read: {{file_path}}"

Directory Operation Events

Directory operation events are emitted when directories are created or deleted.

directory_created

Emitted when a directory is created.

Event Context:

{
  "directory_path": "/path/to/new/directory",
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "Directory created"
    event: "directory_created"
    action:
      type: "command"
      command: "echo"
      args:
        - "Directory created: {{directory_path}}"

directory_deleted

Emitted when a directory is deleted.

Event Context:

{
  "directory_path": "/path/to/deleted/directory",
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "Directory deleted"
    event: "directory_deleted"
    action:
      type: "command"
      command: "echo"
      args:
        - "Directory deleted: {{directory_path}}"

System Events

System events are emitted when ricecoder operations complete.

test_passed

Emitted when tests pass.

Event Context:

{
  "test_file": "/path/to/test.ts",
  "test_count": 42,
  "duration_ms": 1234,
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "Tests passed"
    event: "test_passed"
    action:
      type: "command"
      command: "echo"
      args:
        - "Tests passed! ({{test_count}} tests in {{duration_ms}}ms)"

test_failed

Emitted when tests fail.

Event Context:

{
  "test_file": "/path/to/test.ts",
  "failed_count": 2,
  "passed_count": 40,
  "duration_ms": 1234,
  "error_message": "Expected 42 to equal 43",
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "Tests failed"
    event: "test_failed"
    action:
      type: "ai_prompt"
      prompt_template: |
        Tests failed:
        Failed: {{failed_count}}
        Passed: {{passed_count}}
        Error: {{error_message}}
        
        Suggest fixes.
      model: "gpt-4"
      stream: true

generation_complete

Emitted when code generation completes.

Event Context:

{
  "generated_files": 5,
  "total_lines": 1234,
  "duration_ms": 5678,
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "Generation complete"
    event: "generation_complete"
    action:
      type: "command"
      command: "echo"
      args:
        - "Generated {{generated_files}} files ({{total_lines}} lines)"

build_complete

Emitted when build completes.

Event Context:

{
  "build_status": "success",
  "output_dir": "/path/to/dist",
  "duration_ms": 3456,
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "Build complete"
    event: "build_complete"
    action:
      type: "command"
      command: "echo"
      args:
        - "Build {{build_status}} in {{duration_ms}}ms"

deployment_complete

Emitted when deployment completes.

Event Context:

{
  "deployment_status": "success",
  "environment": "production",
  "version": "1.2.3",
  "duration_ms": 12345,
  "timestamp": "2025-12-05T10:30:00Z"
}

Example Hook:

hooks:
  - name: "Deployment complete"
    event: "deployment_complete"
    action:
      type: "command"
      command: "echo"
      args:
        - "Deployed v{{version}} to {{environment}}"

Event Context Variables

Each event provides context variables that can be used in hooks. Variables are accessed using {{variable_name}} syntax.

Common Variables

All events provide:

  • timestamp: ISO 8601 timestamp of the event

File Operation Variables

File operation events provide:

  • file_path: Path to the file
  • old_path: Previous path (for rename/move events)
  • new_path: New path (for rename/move events)
  • directory_path: Path to the directory
  • size: File size in bytes
  • old_hash: Previous file hash (for modified events)
  • new_hash: New file hash (for modified events)

System Event Variables

System events provide event-specific variables. See event documentation above for details.

Filtering Events

Use conditions to filter which events trigger hooks:

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

Event Ordering

Events are processed in the order they occur. If multiple hooks are registered for the same event, they execute in registration order.

Event Reliability

  • Events are guaranteed to be emitted for all operations
  • Events are processed sequentially (not in parallel)
  • Hook failures do not prevent other hooks from executing
  • Events are not persisted (lost if ricecoder restarts)

Troubleshooting

Event Not Triggering

Problem: Hook is configured for an event but not executing.

Solutions:

  1. Verify event name is correct (case-sensitive)
  2. Check hook is enabled: ricecoder hooks inspect <hook-id>
  3. Verify condition expression is correct
  4. Check logs for event emission: ricecoder logs --filter events

Event Context Variables Missing

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

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 complete reference

See Also

Last updated: December 5, 2025

Clone this wiki locally