259 lines
4.6 KiB
Markdown
259 lines
4.6 KiB
Markdown
---
|
|
summary: "CLI reference for `clawdbot hooks` (agent hooks)"
|
|
read_when:
|
|
- You want to manage agent hooks
|
|
- You want to install or update hooks
|
|
---
|
|
|
|
# `clawdbot hooks`
|
|
|
|
Manage agent hooks (event-driven automations for commands like `/new`, `/reset`, etc.).
|
|
|
|
Related:
|
|
- Hooks: [Hooks](/hooks)
|
|
|
|
## List All Hooks
|
|
|
|
```bash
|
|
clawdbot hooks list
|
|
```
|
|
|
|
List all discovered hooks from workspace, managed, and bundled directories.
|
|
|
|
**Options:**
|
|
- `--eligible`: Show only eligible hooks (requirements met)
|
|
- `--json`: Output as JSON
|
|
- `-v, --verbose`: Show detailed information including missing requirements
|
|
|
|
**Example output:**
|
|
|
|
```
|
|
Hooks (2/2 ready)
|
|
|
|
Ready:
|
|
📝 command-logger ✓ - Log all command events to a centralized audit file
|
|
💾 session-memory ✓ - Save session context to memory when /new command is issued
|
|
```
|
|
|
|
**Example (verbose):**
|
|
|
|
```bash
|
|
clawdbot hooks list --verbose
|
|
```
|
|
|
|
Shows missing requirements for ineligible hooks.
|
|
|
|
**Example (JSON):**
|
|
|
|
```bash
|
|
clawdbot hooks list --json
|
|
```
|
|
|
|
Returns structured JSON for programmatic use.
|
|
|
|
## Get Hook Information
|
|
|
|
```bash
|
|
clawdbot hooks info <name>
|
|
```
|
|
|
|
Show detailed information about a specific hook.
|
|
|
|
**Arguments:**
|
|
- `<name>`: Hook name (e.g., `session-memory`)
|
|
|
|
**Options:**
|
|
- `--json`: Output as JSON
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
clawdbot hooks info session-memory
|
|
```
|
|
|
|
**Output:**
|
|
|
|
```
|
|
💾 session-memory ✓ Ready
|
|
|
|
Save session context to memory when /new command is issued
|
|
|
|
Details:
|
|
Source: clawdbot-bundled
|
|
Path: /path/to/clawdbot/hooks/bundled/session-memory/HOOK.md
|
|
Handler: /path/to/clawdbot/hooks/bundled/session-memory/handler.ts
|
|
Homepage: https://docs.clawd.bot/hooks#session-memory
|
|
Events: command:new
|
|
|
|
Requirements:
|
|
Config: ✓ workspace.dir
|
|
```
|
|
|
|
## Check Hooks Eligibility
|
|
|
|
```bash
|
|
clawdbot hooks check
|
|
```
|
|
|
|
Show summary of hook eligibility status (how many are ready vs. not ready).
|
|
|
|
**Options:**
|
|
- `--json`: Output as JSON
|
|
|
|
**Example output:**
|
|
|
|
```
|
|
Hooks Status
|
|
|
|
Total hooks: 2
|
|
Ready: 2
|
|
Not ready: 0
|
|
```
|
|
|
|
## Enable a Hook
|
|
|
|
```bash
|
|
clawdbot hooks enable <name>
|
|
```
|
|
|
|
Enable a specific hook by adding it to your config (`~/.clawdbot/config.json`).
|
|
|
|
**Arguments:**
|
|
- `<name>`: Hook name (e.g., `session-memory`)
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
clawdbot hooks enable session-memory
|
|
```
|
|
|
|
**Output:**
|
|
|
|
```
|
|
✓ Enabled hook: 💾 session-memory
|
|
```
|
|
|
|
**What it does:**
|
|
- Checks if hook exists and is eligible
|
|
- Updates `hooks.internal.entries.<name>.enabled = true` in your config
|
|
- Saves config to disk
|
|
|
|
**After enabling:**
|
|
- Restart the gateway so hooks reload (menu bar app restart on macOS, or restart your gateway process in dev).
|
|
|
|
## Disable a Hook
|
|
|
|
```bash
|
|
clawdbot hooks disable <name>
|
|
```
|
|
|
|
Disable a specific hook by updating your config.
|
|
|
|
**Arguments:**
|
|
- `<name>`: Hook name (e.g., `command-logger`)
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
clawdbot hooks disable command-logger
|
|
```
|
|
|
|
**Output:**
|
|
|
|
```
|
|
⏸ Disabled hook: 📝 command-logger
|
|
```
|
|
|
|
**After disabling:**
|
|
- Restart the gateway so hooks reload
|
|
|
|
## Install Hooks
|
|
|
|
```bash
|
|
clawdbot hooks install <path-or-spec>
|
|
```
|
|
|
|
Install a hook pack from a local folder/archive or npm.
|
|
|
|
**What it does:**
|
|
- Copies the hook pack into `~/.clawdbot/hooks/<id>`
|
|
- Enables the installed hooks in `hooks.internal.entries.*`
|
|
- Records the install under `hooks.internal.installs`
|
|
|
|
**Options:**
|
|
- `-l, --link`: Link a local directory instead of copying (adds it to `hooks.internal.load.extraDirs`)
|
|
|
|
**Supported archives:** `.zip`, `.tgz`, `.tar.gz`, `.tar`
|
|
|
|
**Examples:**
|
|
|
|
```bash
|
|
# Local directory
|
|
clawdbot hooks install ./my-hook-pack
|
|
|
|
# Local archive
|
|
clawdbot hooks install ./my-hook-pack.zip
|
|
|
|
# NPM package
|
|
clawdbot hooks install @clawdbot/my-hook-pack
|
|
|
|
# Link a local directory without copying
|
|
clawdbot hooks install -l ./my-hook-pack
|
|
```
|
|
|
|
## Update Hooks
|
|
|
|
```bash
|
|
clawdbot hooks update <id>
|
|
clawdbot hooks update --all
|
|
```
|
|
|
|
Update installed hook packs (npm installs only).
|
|
|
|
**Options:**
|
|
- `--all`: Update all tracked hook packs
|
|
- `--dry-run`: Show what would change without writing
|
|
|
|
## Bundled Hooks
|
|
|
|
### session-memory
|
|
|
|
Saves session context to memory when you issue `/new`.
|
|
|
|
**Enable:**
|
|
|
|
```bash
|
|
clawdbot hooks enable session-memory
|
|
```
|
|
|
|
**Output:** `~/clawd/memory/YYYY-MM-DD-slug.md`
|
|
|
|
**See:** [session-memory documentation](/hooks#session-memory)
|
|
|
|
### command-logger
|
|
|
|
Logs all command events to a centralized audit file.
|
|
|
|
**Enable:**
|
|
|
|
```bash
|
|
clawdbot hooks enable command-logger
|
|
```
|
|
|
|
**Output:** `~/.clawdbot/logs/commands.log`
|
|
|
|
**View logs:**
|
|
|
|
```bash
|
|
# Recent commands
|
|
tail -n 20 ~/.clawdbot/logs/commands.log
|
|
|
|
# Pretty-print
|
|
cat ~/.clawdbot/logs/commands.log | jq .
|
|
|
|
# Filter by action
|
|
grep '"action":"new"' ~/.clawdbot/logs/commands.log | jq .
|
|
```
|
|
|
|
**See:** [command-logger documentation](/hooks#command-logger)
|