{
  "title": "My Hook",
  "content": "Detailed documentation goes here...\n\n- Listens for `/new` commands\n- Performs some action\n- Logs the result\n\n- Node.js must be installed\n\nNo configuration needed.\ntypescript theme={null}\nimport type { HookHandler } from \"../../src/hooks/hooks.js\";\n\nconst myHandler: HookHandler = async (event) => {\n  // Only trigger on 'new' command\n  if (event.type !== \"command\" || event.action !== \"new\") {\n    return;\n  }\n\nconsole.log(`[my-hook] New command triggered`);\n  console.log(`  Session: ${event.sessionKey}`);\n  console.log(`  Timestamp: ${event.timestamp.toISOString()}`);\n\n// Your custom logic here\n\n// Optionally send message to user\n  event.messages.push(\"✨ My hook executed!\");\n};\n\nexport default myHandler;\ntypescript theme={null}\n{\n  type: 'command' | 'session' | 'agent' | 'gateway',\n  action: string,              // e.g., 'new', 'reset', 'stop'\n  sessionKey: string,          // Session identifier\n  timestamp: Date,             // When the event occurred\n  messages: string[],          // Push messages here to send to user\n  context: {\n    sessionEntry?: SessionEntry,\n    sessionId?: string,\n    sessionFile?: string,\n    commandSource?: string,    // e.g., 'whatsapp', 'telegram'\n    senderId?: string,\n    workspaceDir?: string,\n    bootstrapFiles?: WorkspaceBootstrapFile[],\n    cfg?: OpenClawConfig\n  }\n}\nbash theme={null}\nmkdir -p ~/.openclaw/hooks/my-hook\ncd ~/.openclaw/hooks/my-hook\nmarkdown theme={null}\n---\nname: my-hook\ndescription: \"Does something useful\"\nmetadata: { \"openclaw\": { \"emoji\": \"🎯\", \"events\": [\"command:new\"] } }\n---",
  "code_samples": [
    {
      "code": "### Metadata Fields\n\nThe `metadata.openclaw` object supports:\n\n* **`emoji`**: Display emoji for CLI (e.g., `\"💾\"`)\n* **`events`**: Array of events to listen for (e.g., `[\"command:new\", \"command:reset\"]`)\n* **`export`**: Named export to use (defaults to `\"default\"`)\n* **`homepage`**: Documentation URL\n* **`requires`**: Optional requirements\n  * **`bins`**: Required binaries on PATH (e.g., `[\"git\", \"node\"]`)\n  * **`anyBins`**: At least one of these binaries must be present\n  * **`env`**: Required environment variables\n  * **`config`**: Required config paths (e.g., `[\"workspace.dir\"]`)\n  * **`os`**: Required platforms (e.g., `[\"darwin\", \"linux\"]`)\n* **`always`**: Bypass eligibility checks (boolean)\n* **`install`**: Installation methods (for bundled hooks: `[{\"id\":\"bundled\",\"kind\":\"bundled\"}]`)\n\n### Handler Implementation\n\nThe `handler.ts` file exports a `HookHandler` function:",
      "language": "unknown"
    },
    {
      "code": "#### Event Context\n\nEach event includes:",
      "language": "unknown"
    },
    {
      "code": "## Event Types\n\n### Command Events\n\nTriggered when agent commands are issued:\n\n* **`command`**: All command events (general listener)\n* **`command:new`**: When `/new` command is issued\n* **`command:reset`**: When `/reset` command is issued\n* **`command:stop`**: When `/stop` command is issued\n\n### Agent Events\n\n* **`agent:bootstrap`**: Before workspace bootstrap files are injected (hooks may mutate `context.bootstrapFiles`)\n\n### Gateway Events\n\nTriggered when the gateway starts:\n\n* **`gateway:startup`**: After channels start and hooks are loaded\n\n### Tool Result Hooks (Plugin API)\n\nThese hooks are not event-stream listeners; they let plugins synchronously adjust tool results before OpenClaw persists them.\n\n* **`tool_result_persist`**: transform tool results before they are written to the session transcript. Must be synchronous; return the updated tool result payload or `undefined` to keep it as-is. See [Agent Loop](/concepts/agent-loop).\n\n### Future Events\n\nPlanned event types:\n\n* **`session:start`**: When a new session begins\n* **`session:end`**: When a session ends\n* **`agent:error`**: When an agent encounters an error\n* **`message:sent`**: When a message is sent\n* **`message:received`**: When a message is received\n\n## Creating Custom Hooks\n\n### 1. Choose Location\n\n* **Workspace hooks** (`<workspace>/hooks/`): Per-agent, highest precedence\n* **Managed hooks** (`~/.openclaw/hooks/`): Shared across workspaces\n\n### 2. Create Directory Structure",
      "language": "unknown"
    },
    {
      "code": "### 3. Create HOOK.md",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "What It Does",
      "id": "what-it-does"
    },
    {
      "level": "h2",
      "text": "Requirements",
      "id": "requirements"
    },
    {
      "level": "h2",
      "text": "Configuration",
      "id": "configuration"
    },
    {
      "level": "h3",
      "text": "Metadata Fields",
      "id": "metadata-fields"
    },
    {
      "level": "h3",
      "text": "Handler Implementation",
      "id": "handler-implementation"
    },
    {
      "level": "h2",
      "text": "Event Types",
      "id": "event-types"
    },
    {
      "level": "h3",
      "text": "Command Events",
      "id": "command-events"
    },
    {
      "level": "h3",
      "text": "Agent Events",
      "id": "agent-events"
    },
    {
      "level": "h3",
      "text": "Gateway Events",
      "id": "gateway-events"
    },
    {
      "level": "h3",
      "text": "Tool Result Hooks (Plugin API)",
      "id": "tool-result-hooks-(plugin-api)"
    },
    {
      "level": "h3",
      "text": "Future Events",
      "id": "future-events"
    },
    {
      "level": "h2",
      "text": "Creating Custom Hooks",
      "id": "creating-custom-hooks"
    },
    {
      "level": "h3",
      "text": "1. Choose Location",
      "id": "1.-choose-location"
    },
    {
      "level": "h3",
      "text": "2. Create Directory Structure",
      "id": "2.-create-directory-structure"
    },
    {
      "level": "h3",
      "text": "3. Create HOOK.md",
      "id": "3.-create-hook.md"
    }
  ],
  "url": "llms-txt#my-hook",
  "links": []
}