let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

refactor: rename clawdbot to moltbot with legacy compat

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-27 12:19:58 +00:00
parent 83460df96f
commit 6d16a658e5
1839 changed files with 11250 additions and 11199 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/hooks.md
View File

@@ -6,14 +6,14 @@ read_when:
---
# Hooks
Hooks provide an extensible event-driven system for automating actions in response to agent commands and events. Hooks are automatically discovered from directories and can be managed via CLI commands, similar to how skills work in Clawdbot.
Hooks provide an extensible event-driven system for automating actions in response to agent commands and events. Hooks are automatically discovered from directories and can be managed via CLI commands, similar to how skills work in Moltbot.
## Getting Oriented
Hooks are small scripts that run when something happens. There are two kinds:
- **Hooks** (this page): run inside the Gateway when agent events fire, like `/new`, `/reset`, `/stop`, or lifecycle events.
- **Webhooks**: external HTTP webhooks that let other systems trigger work in Clawdbot. See [Webhook Hooks](/automation/webhook) or use `clawdbot webhooks` for Gmail helper commands.
- **Webhooks**: external HTTP webhooks that let other systems trigger work in Moltbot. See [Webhook Hooks](/automation/webhook) or use `moltbot webhooks` for Gmail helper commands.
Hooks can also be bundled inside plugins; see [Plugins](/plugin#plugin-hooks).
@@ -31,13 +31,13 @@ The hooks system allows you to:
- Save session context to memory when `/new` is issued
- Log all commands for auditing
- Trigger custom automations on agent lifecycle events
- Extend Clawdbot's behavior without modifying core code
- Extend Moltbot's behavior without modifying core code
## Getting Started
### Bundled Hooks
Clawdbot ships with four bundled hooks that are automatically discovered:
Moltbot ships with four bundled hooks that are automatically discovered:
- **💾 session-memory**: Saves session context to your agent workspace (default `~/clawd/memory/`) when you issue `/new`
- **📝 command-logger**: Logs all command events to `~/.clawdbot/logs/commands.log`
@@ -47,30 +47,30 @@ Clawdbot ships with four bundled hooks that are automatically discovered:
List available hooks:
```bash
clawdbot hooks list
moltbot hooks list
```
Enable a hook:
```bash
clawdbot hooks enable session-memory
moltbot hooks enable session-memory
```
Check hook status:
```bash
clawdbot hooks check
moltbot hooks check
```
Get detailed information:
```bash
clawdbot hooks info session-memory
moltbot hooks info session-memory
```
### Onboarding
During onboarding (`clawdbot onboard`), you'll be prompted to enable recommended hooks. The wizard automatically discovers eligible hooks and presents them for selection.
During onboarding (`moltbot onboard`), you'll be prompted to enable recommended hooks. The wizard automatically discovers eligible hooks and presents them for selection.
## Hook Discovery
@@ -78,7 +78,7 @@ Hooks are automatically discovered from three directories (in order of precedenc
1. **Workspace hooks**: `<workspace>/hooks/` (per-agent, highest precedence)
2. **Managed hooks**: `~/.clawdbot/hooks/` (user-installed, shared across workspaces)
3. **Bundled hooks**: `<clawdbot>/dist/hooks/bundled/` (shipped with Clawdbot)
3. **Bundled hooks**: `<moltbot>/dist/hooks/bundled/` (shipped with Moltbot)
Managed hook directories can be either a **single hook** or a **hook pack** (package directory).
@@ -92,11 +92,11 @@ my-hook/
## Hook Packs (npm/archives)
Hook packs are standard npm packages that export one or more hooks via `clawdbot.hooks` in
Hook packs are standard npm packages that export one or more hooks via `moltbot.hooks` in
`package.json`. Install them with:
```bash
clawdbot hooks install <path-or-spec>
moltbot hooks install <path-or-spec>
```
Example `package.json`:
@@ -105,7 +105,7 @@ Example `package.json`:
{
"name": "@acme/my-hooks",
"version": "0.1.0",
"clawdbot": {
"moltbot": {
"hooks": ["./hooks/my-hook", "./hooks/other-hook"]
}
}
@@ -125,7 +125,7 @@ The `HOOK.md` file contains metadata in YAML frontmatter plus Markdown documenta
name: my-hook
description: "Short description of what this hook does"
homepage: https://docs.molt.bot/hooks#my-hook
metadata: {"clawdbot":{"emoji":"🔗","events":["command:new"],"requires":{"bins":["node"]}}}
metadata: {"moltbot":{"emoji":"🔗","events":["command:new"],"requires":{"bins":["node"]}}}
---
# My Hook
@@ -209,7 +209,7 @@ Each event includes:
senderId?: string,
workspaceDir?: string,
bootstrapFiles?: WorkspaceBootstrapFile[],
cfg?: ClawdbotConfig
cfg?: MoltbotConfig
}
}
```
@@ -237,7 +237,7 @@ Triggered when the gateway starts:
### Tool Result Hooks (Plugin API)
These hooks are not event-stream listeners; they let plugins synchronously adjust tool results before Clawdbot persists them.
These hooks are not event-stream listeners; they let plugins synchronously adjust tool results before Moltbot persists them.
- **`tool_result_persist`**: transform tool results before they are written to the session transcript. Must be synchronous; return the updated tool result payload or `undefined` to keep it as-is. See [Agent Loop](/concepts/agent-loop).
@@ -271,7 +271,7 @@ cd ~/.clawdbot/hooks/my-hook
---
name: my-hook
description: "Does something useful"
metadata: {"clawdbot":{"emoji":"🎯","events":["command:new"]}}
metadata: {"moltbot":{"emoji":"🎯","events":["command:new"]}}
---
# My Custom Hook
@@ -300,10 +300,10 @@ export default handler;
```bash
# Verify hook is discovered
clawdbot hooks list
moltbot hooks list
# Enable it
clawdbot hooks enable my-hook
moltbot hooks enable my-hook
# Restart your gateway process (menu bar app restart on macOS, or restart your dev process)
@@ -397,46 +397,46 @@ The old config format still works for backwards compatibility:
```bash
# List all hooks
clawdbot hooks list
moltbot hooks list
# Show only eligible hooks
clawdbot hooks list --eligible
moltbot hooks list --eligible
# Verbose output (show missing requirements)
clawdbot hooks list --verbose
moltbot hooks list --verbose
# JSON output
clawdbot hooks list --json
moltbot hooks list --json
```
### Hook Information
```bash
# Show detailed info about a hook
clawdbot hooks info session-memory
moltbot hooks info session-memory
# JSON output
clawdbot hooks info session-memory --json
moltbot hooks info session-memory --json
```
### Check Eligibility
```bash
# Show eligibility summary
clawdbot hooks check
moltbot hooks check
# JSON output
clawdbot hooks check --json
moltbot hooks check --json
```
### Enable/Disable
```bash
# Enable a hook
clawdbot hooks enable session-memory
moltbot hooks enable session-memory
# Disable a hook
clawdbot hooks disable command-logger
moltbot hooks disable command-logger
```
## Bundled Hooks
@@ -475,7 +475,7 @@ Saves session context to memory when you issue `/new`.
**Enable**:
```bash
clawdbot hooks enable session-memory
moltbot hooks enable session-memory
```
### command-logger
@@ -516,7 +516,7 @@ grep '"action":"new"' ~/.clawdbot/logs/commands.log | jq .
**Enable**:
```bash
clawdbot hooks enable command-logger
moltbot hooks enable command-logger
```
### soul-evil
@@ -532,7 +532,7 @@ Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by
**Enable**:
```bash
clawdbot hooks enable soul-evil
moltbot hooks enable soul-evil
```
**Config**:
@@ -572,7 +572,7 @@ Internal hooks must be enabled for this to run.
**Enable**:
```bash
clawdbot hooks enable boot-md
moltbot hooks enable boot-md
```
## Best Practices
@@ -629,13 +629,13 @@ const handler: HookHandler = async (event) => {
Specify exact events in metadata when possible:
```yaml
metadata: {"clawdbot":{"events":["command:new"]}} # Specific
metadata: {"moltbot":{"events":["command:new"]}} # Specific
```
Rather than:
```yaml
metadata: {"clawdbot":{"events":["command"]}} # General - more overhead
metadata: {"moltbot":{"events":["command"]}} # General - more overhead
```
## Debugging
@@ -655,7 +655,7 @@ Registered hook: boot-md -> gateway:startup
List all discovered hooks:
```bash
clawdbot hooks list --verbose
moltbot hooks list --verbose
```
### Check Registration
@@ -674,7 +674,7 @@ const handler: HookHandler = async (event) => {
Check why a hook isn't eligible:
```bash
clawdbot hooks info my-hook
moltbot hooks info my-hook
```
Look for missing requirements in the output.
@@ -777,7 +777,7 @@ Session reset
3. List all discovered hooks:
```bash
clawdbot hooks list
moltbot hooks list
```
### Hook Not Eligible
@@ -785,7 +785,7 @@ Session reset
Check requirements:
```bash
clawdbot hooks info my-hook
moltbot hooks info my-hook
```
Look for missing:
@@ -798,7 +798,7 @@ Look for missing:
1. Verify hook is enabled:
```bash
clawdbot hooks list
moltbot hooks list
# Should show ✓ next to enabled hooks
```
@@ -853,7 +853,7 @@ node -e "import('./path/to/handler.ts').then(console.log)"
---
name: my-hook
description: "My custom hook"
metadata: {"clawdbot":{"emoji":"🎯","events":["command:new"]}}
metadata: {"moltbot":{"emoji":"🎯","events":["command:new"]}}
---
# My Hook
@@ -877,7 +877,7 @@ node -e "import('./path/to/handler.ts').then(console.log)"
4. Verify and restart your gateway process:
```bash
clawdbot hooks list
moltbot hooks list
# Should show: 🎯 my-hook ✓
```
@@ -891,6 +891,6 @@ node -e "import('./path/to/handler.ts').then(console.log)"
## See Also
- [CLI Reference: hooks](/cli/hooks)
- [Bundled Hooks README](https://github.com/clawdbot/clawdbot/tree/main/src/hooks/bundled)
- [Bundled Hooks README](https://github.com/moltbot/moltbot/tree/main/src/hooks/bundled)
- [Webhook Hooks](/automation/webhook)
- [Configuration](/gateway/configuration#hooks)