Skip to content

Commit 3a6ee5e

Browse files
steipetesteipete
committed
feat: unify hooks installs and webhooks
1 parent 5dc87a2 commit 3a6ee5e

33 files changed

Lines changed: 2235 additions & 829 deletions

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@
1515
- **BREAKING:** Drop legacy `chatType: "room"` support; use `chatType: "channel"`.
1616
- **BREAKING:** remove legacy provider-specific target resolution fallbacks; target resolution is centralized with plugin hints + directory lookups.
1717
- **BREAKING:** drop legacy target normalization helpers; use outbound target normalization and resolver flows.
18+
- **BREAKING:** `clawdbot hooks` is now `clawdbot webhooks`; internal hooks live under `clawdbot hooks`.
19+
- **BREAKING:** `clawdbot plugins install <path>` now copies into `~/.clawdbot/extensions` (use `--link` to keep path-based loading).
1820

1921
### Changes
2022
- Tools: improve `web_fetch` extraction using Readability (with fallback).
@@ -37,6 +39,8 @@
3739
- Docs: add `/help` hub, Node/npm PATH guide, and expand directory CLI docs.
3840
- Config: support env var substitution in config values. (#1044) — thanks @sebslight.
3941
- Health: add per-agent session summaries and account-level health details, and allow selective probes. (#1047) — thanks @gumadeiras.
42+
- Hooks: add hook pack installs (npm/path/zip/tar) with `clawdbot.hooks` manifests and `clawdbot hooks install/update`.
43+
- Plugins: add zip installs and `--link` to avoid copying local paths.
4044

4145
### Fixes
4246
- Sub-agents: normalize announce delivery origin + queue bucketing by accountId to keep multi-account routing stable. (#1061, #1058) — thanks @adam91holt.

‎docs/automation/gmail-pubsub.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -92,13 +92,13 @@ under `hooks.transformsDir` (see [Webhooks](/automation/webhook)).
9292
Use the Clawdbot helper to wire everything together (installs deps on macOS via brew):
9393

9494
```bash
95-
clawdbot hooks gmail setup \
95+
clawdbot webhooks gmail setup \
9696
--account [email protected]
9797
```
9898

9999
Defaults:
100100
- Uses Tailscale Funnel for the public push endpoint.
101-
- Writes `hooks.gmail` config for `clawdbot hooks gmail run`.
101+
- Writes `hooks.gmail` config for `clawdbot webhooks gmail run`.
102102
- Enables the Gmail hook preset (`hooks.presets: ["gmail"]`).
103103

104104
Path note: when `tailscale.mode` is enabled, Clawdbot automatically sets
@@ -124,7 +124,7 @@ Gateway auto-start (recommended):
124124
Manual daemon (starts `gog gmail watch serve` + auto-renew):
125125

126126
```bash
127-
clawdbot hooks gmail run
127+
clawdbot webhooks gmail run
128128
```
129129

130130
## One-time setup
@@ -191,7 +191,7 @@ Notes:
191191
- `--hook-url` points to Clawdbot `/hooks/gmail` (mapped; isolated run + summary to main).
192192
- `--include-body` and `--max-bytes` control the body snippet sent to Clawdbot.
193193

194-
Recommended: `clawdbot hooks gmail run` wraps the same flow and auto-renews the watch.
194+
Recommended: `clawdbot webhooks gmail run` wraps the same flow and auto-renews the watch.
195195

196196
## Expose the handler (advanced, unsupported)
197197

‎docs/automation/webhook.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ Mapping options (summary):
9696
- TS transforms require a TS loader (e.g. `bun` or `tsx`) or precompiled `.js` at runtime.
9797
- Set `deliver: true` + `channel`/`to` on mappings to route replies to a chat surface
9898
(`channel` defaults to `last` and falls back to WhatsApp).
99-
- `clawdbot hooks gmail setup` writes `hooks.gmail` config for `clawdbot hooks gmail run`.
99+
- `clawdbot webhooks gmail setup` writes `hooks.gmail` config for `clawdbot webhooks gmail run`.
100100
See [Gmail Pub/Sub](/automation/gmail-pubsub) for the full Gmail watch flow.
101101

102102
## Responses

‎docs/cli/hooks.md‎

Lines changed: 67 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,21 @@
11
---
2-
summary: "CLI reference for `clawdbot hooks` (internal hooks + Gmail Pub/Sub + webhook helpers)"
2+
summary: "CLI reference for `clawdbot hooks` (internal hooks)"
33
read_when:
44
- You want to manage internal agent hooks
5-
- You want to wire Gmail Pub/Sub events into Clawdbot hooks
6-
- You want to run the gog watch service and renew loop
5+
- You want to install or update internal hooks
76
---
87

98
# `clawdbot hooks`
109

11-
Webhook helpers and hook-based integrations.
10+
Manage internal agent hooks (event-driven automations for commands like `/new`, `/reset`, etc.).
1211

1312
Related:
1413
- Internal Hooks: [Internal Agent Hooks](/internal-hooks)
15-
- Webhooks: [Webhook](/automation/webhook)
16-
- Gmail Pub/Sub: [Gmail Pub/Sub](/automation/gmail-pubsub)
17-
18-
## Internal Hooks
1914

20-
Manage internal agent hooks (event-driven automations for commands like `/new`, `/reset`, etc.).
21-
22-
### List All Hooks
15+
## List All Hooks
2316

2417
```bash
25-
clawdbot hooks internal list
18+
clawdbot hooks list
2619
```
2720

2821
List all discovered internal hooks from workspace, managed, and bundled directories.
@@ -45,23 +38,23 @@ Ready:
4538
**Example (verbose):**
4639

4740
```bash
48-
clawdbot hooks internal list --verbose
41+
clawdbot hooks list --verbose
4942
```
5043

5144
Shows missing requirements for ineligible hooks.
5245

5346
**Example (JSON):**
5447

5548
```bash
56-
clawdbot hooks internal list --json
49+
clawdbot hooks list --json
5750
```
5851

5952
Returns structured JSON for programmatic use.
6053

61-
### Get Hook Information
54+
## Get Hook Information
6255

6356
```bash
64-
clawdbot hooks internal info <name>
57+
clawdbot hooks info <name>
6558
```
6659

6760
Show detailed information about a specific hook.
@@ -75,7 +68,7 @@ Show detailed information about a specific hook.
7568
**Example:**
7669

7770
```bash
78-
clawdbot hooks internal info session-memory
71+
clawdbot hooks info session-memory
7972
```
8073

8174
**Output:**
@@ -96,10 +89,10 @@ Requirements:
9689
Config: ✓ workspace.dir
9790
```
9891

99-
### Check Hooks Eligibility
92+
## Check Hooks Eligibility
10093

10194
```bash
102-
clawdbot hooks internal check
95+
clawdbot hooks check
10396
```
10497

10598
Show summary of hook eligibility status (how many are ready vs. not ready).
@@ -117,10 +110,10 @@ Ready: 2
117110
Not ready: 0
118111
```
119112

120-
### Enable a Hook
113+
## Enable a Hook
121114

122115
```bash
123-
clawdbot hooks internal enable <name>
116+
clawdbot hooks enable <name>
124117
```
125118

126119
Enable a specific hook by adding it to your config (`~/.clawdbot/config.json`).
@@ -131,7 +124,7 @@ Enable a specific hook by adding it to your config (`~/.clawdbot/config.json`).
131124
**Example:**
132125

133126
```bash
134-
clawdbot hooks internal enable session-memory
127+
clawdbot hooks enable session-memory
135128
```
136129

137130
**Output:**
@@ -148,10 +141,10 @@ clawdbot hooks internal enable session-memory
148141
**After enabling:**
149142
- Restart the gateway so hooks reload (menu bar app restart on macOS, or restart your gateway process in dev).
150143

151-
### Disable a Hook
144+
## Disable a Hook
152145

153146
```bash
154-
clawdbot hooks internal disable <name>
147+
clawdbot hooks disable <name>
155148
```
156149

157150
Disable a specific hook by updating your config.
@@ -162,7 +155,7 @@ Disable a specific hook by updating your config.
162155
**Example:**
163156

164157
```bash
165-
clawdbot hooks internal disable command-logger
158+
clawdbot hooks disable command-logger
166159
```
167160

168161
**Output:**
@@ -174,6 +167,53 @@ clawdbot hooks internal disable command-logger
174167
**After disabling:**
175168
- Restart the gateway so hooks reload
176169

170+
## Install Hooks
171+
172+
```bash
173+
clawdbot hooks install <path-or-spec>
174+
```
175+
176+
Install a hook pack from a local folder/archive or npm.
177+
178+
**What it does:**
179+
- Copies the hook pack into `~/.clawdbot/hooks/<id>`
180+
- Enables the installed hooks in `hooks.internal.entries.*`
181+
- Records the install under `hooks.internal.installs`
182+
183+
**Options:**
184+
- `-l, --link`: Link a local directory instead of copying (adds it to `hooks.internal.load.extraDirs`)
185+
186+
**Supported archives:** `.zip`, `.tgz`, `.tar.gz`, `.tar`
187+
188+
**Examples:**
189+
190+
```bash
191+
# Local directory
192+
clawdbot hooks install ./my-hook-pack
193+
194+
# Local archive
195+
clawdbot hooks install ./my-hook-pack.zip
196+
197+
# NPM package
198+
clawdbot hooks install @clawdbot/my-hook-pack
199+
200+
# Link a local directory without copying
201+
clawdbot hooks install -l ./my-hook-pack
202+
```
203+
204+
## Update Hooks
205+
206+
```bash
207+
clawdbot hooks update <id>
208+
clawdbot hooks update --all
209+
```
210+
211+
Update installed hook packs (npm installs only).
212+
213+
**Options:**
214+
- `--all`: Update all tracked hook packs
215+
- `--dry-run`: Show what would change without writing
216+
177217
## Bundled Hooks
178218

179219
### session-memory
@@ -183,7 +223,7 @@ Saves session context to memory when you issue `/new`.
183223
**Enable:**
184224

185225
```bash
186-
clawdbot hooks internal enable session-memory
226+
clawdbot hooks enable session-memory
187227
```
188228

189229
**Output:** `~/clawd/memory/YYYY-MM-DD-slug.md`
@@ -197,7 +237,7 @@ Logs all command events to a centralized audit file.
197237
**Enable:**
198238

199239
```bash
200-
clawdbot hooks internal enable command-logger
240+
clawdbot hooks enable command-logger
201241
```
202242

203243
**Output:** `~/.clawdbot/logs/commands.log`
@@ -216,12 +256,3 @@ grep '"action":"new"' ~/.clawdbot/logs/commands.log | jq .
216256
```
217257

218258
**See:** [command-logger documentation](/internal-hooks#command-logger)
219-
220-
## Gmail
221-
222-
```bash
223-
clawdbot hooks gmail setup --account [email protected]
224-
clawdbot hooks gmail run
225-
```
226-
227-
See [Gmail Pub/Sub documentation](/automation/gmail-pubsub) for details.

‎docs/cli/index.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ This page describes the current CLI behavior. If commands change, update this do
4040
- [`dns`](/cli/dns)
4141
- [`docs`](/cli/docs)
4242
- [`hooks`](/cli/hooks)
43+
- [`webhooks`](/cli/webhooks)
4344
- [`pairing`](/cli/pairing)
4445
- [`plugins`](/cli/plugins) (plugin commands)
4546
- [`channels`](/cli/channels)
@@ -212,6 +213,14 @@ clawdbot [--dev] [--profile <name>] <command>
212213
console
213214
pdf
214215
hooks
216+
list
217+
info
218+
check
219+
enable
220+
disable
221+
install
222+
update
223+
webhooks
215224
gmail setup|run
216225
pairing
217226
list
@@ -414,12 +423,12 @@ Subcommands:
414423
- `pairing list <channel> [--json]`
415424
- `pairing approve <channel> <code> [--notify]`
416425

417-
### `hooks gmail`
426+
### `webhooks gmail`
418427
Gmail Pub/Sub hook setup + runner. See [/automation/gmail-pubsub](/automation/gmail-pubsub).
419428

420429
Subcommands:
421-
- `hooks gmail setup` (requires `--account <email>`; supports `--project`, `--topic`, `--subscription`, `--label`, `--hook-url`, `--hook-token`, `--push-token`, `--bind`, `--port`, `--path`, `--include-body`, `--max-bytes`, `--renew-minutes`, `--tailscale`, `--tailscale-path`, `--tailscale-target`, `--push-endpoint`, `--json`)
422-
- `hooks gmail run` (runtime overrides for the same flags)
430+
- `webhooks gmail setup` (requires `--account <email>`; supports `--project`, `--topic`, `--subscription`, `--label`, `--hook-url`, `--hook-token`, `--push-token`, `--bind`, `--port`, `--path`, `--include-body`, `--max-bytes`, `--renew-minutes`, `--tailscale`, `--tailscale-path`, `--tailscale-target`, `--push-endpoint`, `--json`)
431+
- `webhooks gmail run` (runtime overrides for the same flags)
423432

424433
### `dns setup`
425434
Wide-area discovery DNS helper (CoreDNS + Tailscale). See [/gateway/discovery](/gateway/discovery).

‎docs/cli/plugins.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,19 @@ clawdbot plugins update --all
2828
### Install
2929

3030
```bash
31-
clawdbot plugins install <npm-spec>
31+
clawdbot plugins install <path-or-spec>
3232
```
3333

3434
Security note: treat plugin installs like running code. Prefer pinned versions.
3535

36+
Supported archives: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
37+
38+
Use `--link` to avoid copying a local directory (adds to `plugins.load.paths`):
39+
40+
```bash
41+
clawdbot plugins install -l ./my-plugin
42+
```
43+
3644
### Update
3745

3846
```bash

‎docs/cli/webhooks.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
summary: "CLI reference for `clawdbot webhooks` (webhook helpers + Gmail Pub/Sub)"
3+
read_when:
4+
- You want to wire Gmail Pub/Sub events into Clawdbot
5+
- You want webhook helper commands
6+
---
7+
8+
# `clawdbot webhooks`
9+
10+
Webhook helpers and integrations (Gmail Pub/Sub, webhook helpers).
11+
12+
Related:
13+
- Webhooks: [Webhook](/automation/webhook)
14+
- Gmail Pub/Sub: [Gmail Pub/Sub](/automation/gmail-pubsub)
15+
16+
## Gmail
17+
18+
```bash
19+
clawdbot webhooks gmail setup --account [email protected]
20+
clawdbot webhooks gmail run
21+
```
22+
23+
See [Gmail Pub/Sub documentation](/automation/gmail-pubsub) for details.

‎docs/gateway/configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2757,7 +2757,7 @@ Mapping notes:
27572757
- If there is no prior delivery route, set `channel` + `to` explicitly (required for Telegram/Discord/Slack/Signal/iMessage/MS Teams).
27582758
- `model` overrides the LLM for this hook run (`provider/model` or alias; must be allowed if `agents.defaults.models` is set).
27592759

2760-
Gmail helper config (used by `clawdbot hooks gmail setup` / `run`):
2760+
Gmail helper config (used by `clawdbot webhooks gmail setup` / `run`):
27612761

27622762
```json5
27632763
{

0 commit comments

Comments
 (0)