> ## 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 OpenClaw 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

### `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.
</Note>

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](/developers/hooks) for the full hook authoring guide, including the handler signature, all available events, and `HOOK.md` frontmatter format.

## Related

* [Hooks (developer guide)](/developers/hooks)
* [CLI reference - hooks](/reference/cli#openclaw-hooks)
* [Gateway configuration - hooks section](/reference/config#hooks-incoming-webhooks-and-lifecycle-hooks)