> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks catalogue

> All bundled WednesdayAI hooks: events, configuration, and handler contract.

# Hooks catalogue

WednesdayAI ships five bundled hooks. They are auto-discovered from `dist/hooks/bundled/` and managed via the CLI.

```bash theme={"dark"}
openclaw hooks list            # show all hooks with enabled/disabled status
openclaw hooks info <name>     # requirements, config, current status
openclaw hooks check           # verify all enabled hooks can load
openclaw hooks enable <name>
openclaw hooks disable <name>
openclaw hooks install <path>  # install a custom hook
openclaw hooks update <name>   # update an installed hook
```

During onboarding (`openclaw onboard`), the wizard prompts you to enable recommended hooks.

***

## Bundled hooks

The following five hooks ship with WednesdayAI and are managed via the CLI.

### `session-memory`

Saves session context to the agent workspace when you issue `/new` or `/reset`. Useful for giving the agent a memory of previous sessions.

| Property | Value |
| - | - |
| **Events** | `command:new`, `command:reset` |
| **Writes to** | `<workspace>/memory/YYYY-MM-DD-slug.md` |
| **Requires** | `workspace.dir` |
| **Emoji** | 💾 |

**Enable:**

```bash theme={"dark"}
openclaw hooks enable session-memory
```

**What it does:** when a session resets, it locates the pre-reset transcript, extracts the last N user/assistant messages (default 15), generates a descriptive slug, writes a structured summary to the workspace memory directory, and confirms the file path. On the next session start the agent can read this file if memory search tools are configured.

#### Configuring injected message counts

```json5 theme={"dark"}
// hooks.internal.entries["session-memory"]
{
  hooks: {
    internal: {
      entries: {
        "session-memory": {
          messages: 25,   // max memory entries to inject (default: 15)
        },
      },
    },
  },
}
```

***

### `session-journal`

Writes a reflective LLM journal entry to the agent's `journal/` folder when an opted-in agent issues `/new` or `/reset`. Unlike most bundled hooks, this hook is enabled **per-agent** rather than globally — there is no `hooks.internal.entries` key for it.

| Property | Value |
| - | - |
| **Events** | `command:new`, `command:reset` |
| **Writes to** | `<workspace>/journal/YYYY-MM-DD-HHMMss-<slug>.md` |
| **Requires** | `workspace.dir` |
| **Emoji** | 📔 |

**Enable:** add `sessionJournal.enabled: true` to the agent's entry in `openclaw.json`:

```json theme={"dark"}
{
  "agents": {
    "list": [
      {
        "id": "claire",
        "sessionJournal": {
          "enabled": true,
          "prompt": "Write structured patient notes..."
        }
      }
    ]
  }
}
```

Set `sessionJournal.enabled: false` (or omit the key entirely) to disable for a specific agent. The `prompt` field is optional; the default targets patient-notes / coaching-journal style entries.

**What it does:** on `/new` or `/reset`, the hook calls the LLM with the current session transcript and the configured prompt, generates a slug from the response, and writes the journal entry to `<effectiveWorkspaceDir>/journal/YYYY-MM-DD-HHMMss-<slug>.md`. When `workspaceLane` is in context, `effectiveWorkspaceDir` is the lane-local directory; otherwise it falls back to the agent's configured workspace.

**Limitations:** journal entries are written only when a session explicitly resets via `/new` or `/reset`. Sessions that end via process exit, connection drop, or idle timeout do not produce an entry. The `/new` and `/reset` commands block until the LLM call completes (up to \~15 s) — disable this hook for an agent if that latency is unacceptable.

***

### `bootstrap-extra-files`

Injects additional files from configured glob/path patterns into the agent workspace during bootstrap. Used to include extra context roots (for example monorepo `AGENTS.md`/`TOOLS.md` files) without changing the workspace root.

| Property | Value |
| - | - |
| **Event** | `agent:bootstrap` |
| **Reads from** | Configured glob patterns |
| **Requires** | `workspace.dir` |
| **Emoji** | 📎 |

**Enable:**

```bash theme={"dark"}
openclaw hooks enable bootstrap-extra-files
```

**Configure paths in `~/.openclaw/openclaw.json`:**

```json5 theme={"dark"}
{
  hooks: {
    internal: {
      enabled: true,
      entries: {
        "bootstrap-extra-files": {
          enabled: true,
          paths: ["packages/*/AGENTS.md", "packages/*/TOOLS.md"],
        },
      },
    },
  },
}
```

***

### `command-logger`

Logs all command events to a local log file. Provides an audit trail of every `/command` sent to the gateway.

| Property | Value |
| - | - |
| **Event** | `command` (all `/new`, `/reset`, `/stop`, ... events) |
| **Writes to** | `~/.openclaw/logs/commands.log` |
| **Emoji** | 📝 |

**Enable:**

```bash theme={"dark"}
openclaw hooks enable command-logger
```

**Log format** (JSONL, one entry per line):

```json theme={"dark"}
{"timestamp":"2026-05-27T12:34:56.789Z","action":"new","sessionKey":"agent:main:main","senderId":"+15555550123","source":"telegram"}
```

***

### `boot-md`

Runs `BOOT.md` from each configured agent's resolved workspace at gateway startup. Useful for injecting startup instructions or running an initialisation checklist.

| Property | Value |
| - | - |
| **Event** | `gateway:startup` |
| **Reads from** | `<workspace>/BOOT.md` |
| **Requires** | `workspace.dir` |
| **Emoji** | 🚀 |

**Enable:**

```bash theme={"dark"}
openclaw hooks enable boot-md
```

***

## Standalone hook events

These are runtime events that `HOOK.md` handlers can subscribe to. They are emitted by the WednesdayAI runtime and are not bundled hooks.

### `message:sent`

Fires after WednesdayAI delivers a reply to the channel and receives delivery confirmation.

| Property | Value |
| - | - |
| **When** | After outbound message delivery |
| **Mutating** | No |

**Payload:**

```typescript theme={"dark"}
{
  to: string           // recipient identifier
  content: string
  success: boolean     // whether delivery succeeded
  error?: string       // present if success is false
  channelId: string
  accountId?: string
  conversationId?: string
  messageId?: string
  isGroup?: boolean
  groupId?: string
}
```

**Use cases:** Audit logging, analytics, post-send side-effects.

***

## Lifecycle plugin hooks

Lifecycle plugin hooks are the `api.on(...)` surface defined by the `PluginHookName` union in `src/plugins/types.ts` — model resolution, prompt build, LLM input/output, tool calls, message and session lifecycle, subagents, gateway start/stop, and the `context.*` / `compaction.plan` context-engine hooks. The full contract with event shapes and mutation semantics lives in the [Plugin hooks reference](https://docs.wednesdayai.dev/next/reference/plugin-hooks.md); the hook below is one mutating example from that set.

### `subagent_spawning`

> [!NOTE]
>
> `subagent_spawning` is a lifecycle plugin hook, not a standalone hook event. It can only be used
> inside a plugin via `api.on("subagent_spawning", handler)`. It cannot be subscribed to from a
> `HOOK.md` file.

Fires when a subagent is about to spawn. Allows a plugin to inspect or modify the spawn before it occurs.

| Property | Value |
| - | - |
| **When** | Before a subagent spawn |
| **Mutating** | Yes |
| **Registration** | `api.on("subagent_spawning", handler)` inside a plugin |

#### Return shape

The handler must return one of:

```typescript theme={"dark"}
| { status: "ok"; threadBindingReady?: boolean }
| { status: "error"; error: string }
```

Return `{ status: "ok" }` to allow the spawn, `{ status: "ok", threadBindingReady: true }` if a thread binding is ready, or `{ status: "error", error: "reason" }` to block the spawn.

***

## Hook discovery order

Hooks are discovered in this order (highest precedence first):

1. `<workspace>/hooks/` - per-agent hooks
2. `~/.openclaw/hooks/` - user-installed shared hooks
3. `<openclaw>/dist/hooks/bundled/` - bundled hooks (this catalogue)

A hook in a higher-precedence directory overrides one with the same `name` in a lower-precedence directory.

## Installing custom hooks

```bash theme={"dark"}
openclaw hooks install ./path/to/my-hook
openclaw hooks install @wednesdayai/my-hook-pack
```

Dependencies are installed with `npm install --ignore-scripts`. Keep hook dependencies to pure JS/TS packages with no `postinstall` build steps.

## Writing a hook

See [Hooks](https://docs.wednesdayai.dev/next/developers/hooks.md) for the full hook authoring guide, including the handler signature, all available events, and `HOOK.md` frontmatter format.

## Related

* [Hooks (developer guide)](https://docs.wednesdayai.dev/next/developers/hooks.md)
* [CLI reference - hooks](https://docs.wednesdayai.dev/next/reference/cli.md#openclaw-hooks)
* [Gateway configuration - hooks section](https://docs.wednesdayai.dev/next/reference/config.md#hooks-incoming-webhooks-and-lifecycle-hooks)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.