What is a HookSystem?

A small event-emitter pattern that stores callbacks by hook name and executes them via register, trigger, and waterfall.

How does waterfall differ from trigger?

Waterfall passes an initial value through each callback, letting plugins transform it sequentially; trigger runs all callbacks and collects their results.

Is the system asynchronous?

Yes—callbacks can be async, and trigger/waterfall await each promise to complete before continuing.

plugin-hook-system

npx machina-cli add skill a5c-ai/babysitter/plugin-hook-system --openclaw

Files (1)

SKILL.md

1.1 KB

Plugin Hook System

Generate hook-based plugin extension system.

Generated Patterns

type HookCallback = (...args: any[]) => Promise<any> | any;

export class HookSystem {
  private hooks = new Map<string, HookCallback[]>();

  register(hookName: string, callback: HookCallback): void {
    const callbacks = this.hooks.get(hookName) || [];
    callbacks.push(callback);
    this.hooks.set(hookName, callbacks);
  }

  async trigger(hookName: string, ...args: any[]): Promise<any[]> {
    const callbacks = this.hooks.get(hookName) || [];
    const results = [];
    for (const cb of callbacks) {
      results.push(await cb(...args));
    }
    return results;
  }

  async waterfall<T>(hookName: string, initial: T): Promise<T> {
    const callbacks = this.hooks.get(hookName) || [];
    let result = initial;
    for (const cb of callbacks) {
      result = await cb(result);
    }
    return result;
  }
}

Target Processes

plugin-architecture-implementation

Source

git clone https://github.com/a5c-ai/babysitter/blob/main/plugins/babysitter/skills/babysit/process/specializations/cli-mcp-development/skills/plugin-hook-system/SKILL.md

View on GitHub

Overview

Generates a hook-based plugin extension system that lets modules register callbacks to named hooks and execute them in order. It includes general register/trigger semantics and a waterfall runner for sequential data transformation. This pattern enables modular, extensible architectures with predictable plugin behavior.

How This Skill Works

Hooks are stored in a map as HookCallback arrays. register adds a callback to a named hook, and trigger runs all callbacks for that hook, aggregating results. waterfall passes an initial value through each callback in sequence, allowing plugins to transform data step by step.

When to Use It

When you want runtime extensibility by letting plugins subscribe to named hooks.
When you need to collect and aggregate results from multiple listeners in a predictable order.
When third-party modules should hook into the app lifecycle without tight coupling.
When you want a plugin to progressively transform data via a waterfall flow.
When building a modular architecture where plugins can be enabled/disabled independently.

Quick Start

Step 1: Implement HookSystem with register, trigger, and waterfall methods.
Step 2: Register plugin callbacks with meaningful hook names (e.g., 'onInit', 'transform').
Step 3: Use trigger to run all callbacks or waterfall to transform data through plugins.

Best Practices

Use clear, stable hook names and document expected arguments and return values.
Keep callbacks small and side-effect free to avoid cascading issues.
Prefer waterfall hooks for explicit data flow rather than global state changes.
Handle async callbacks robustly; support promises and error handling in hooks.
Provide a clean teardown path to unregister or disable hooks during shutdown.

Example Use Cases

A CLI tool where plugins register hooks to extend commands and options.
A build system where plugins transform config or assets via waterfall hooks.
Telemetry or analytics plugins that emit results through a shared hook channel.
Theming or UI customization via render or paint hooks in the app lifecycle.
Middleware-like data processing where each plugin can modify request/response.

Frequently Asked Questions

Add this skill to your agents