Hooks catalogue

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

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:

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

// 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:

{
  "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:

openclaw hooks enable bootstrap-extra-files

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

{
  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:

openclaw hooks enable command-logger

Log format (JSONL, one entry per line):

{"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:

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:

{
  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; the hook below is one mutating example from that set.

`subagent_spawning`

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:

| { 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):

<workspace>/hooks/ - per-agent hooks
~/.openclaw/hooks/ - user-installed shared hooks
<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

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 for the full hook authoring guide, including the handler signature, all available events, and HOOK.md frontmatter format.

​Hooks catalogue

​Bundled hooks

​session-memory

​Configuring injected message counts

​session-journal

​bootstrap-extra-files

​command-logger

​boot-md

​Standalone hook events

​message:sent

​Lifecycle plugin hooks

​subagent_spawning

​Return shape

​Hook discovery order

​Installing custom hooks

​Writing a hook

​Related

Hooks catalogue

Bundled hooks

`session-memory`

Configuring injected message counts

`session-journal`

`bootstrap-extra-files`

`command-logger`

`boot-md`

Standalone hook events

`message:sent`

Lifecycle plugin hooks

`subagent_spawning`

Return shape

Hook discovery order

Installing custom hooks

Writing a hook

Related