194 lines
4.3 KiB
Markdown
194 lines
4.3 KiB
Markdown
# Bundled Internal Hooks
|
|
|
|
This directory contains internal hooks that ship with Clawdbot. These hooks are automatically discovered and can be enabled/disabled via CLI or configuration.
|
|
|
|
## Available Hooks
|
|
|
|
### 💾 session-memory
|
|
|
|
Automatically saves session context to memory when you issue `/new`.
|
|
|
|
**Events**: `command:new`
|
|
**What it does**: Creates a dated memory file with LLM-generated slug based on conversation content.
|
|
**Output**: `<workspace>/memory/YYYY-MM-DD-slug.md` (defaults to `~/clawd`)
|
|
|
|
**Enable**:
|
|
|
|
```bash
|
|
clawdbot hooks internal enable session-memory
|
|
```
|
|
|
|
### 📝 command-logger
|
|
|
|
Logs all command events to a centralized audit file.
|
|
|
|
**Events**: `command` (all commands)
|
|
**What it does**: Appends JSONL entries to command log file.
|
|
**Output**: `~/.clawdbot/logs/commands.log`
|
|
|
|
**Enable**:
|
|
|
|
```bash
|
|
clawdbot hooks internal enable command-logger
|
|
```
|
|
|
|
## Hook Structure
|
|
|
|
Each hook is a directory containing:
|
|
|
|
- **HOOK.md**: Metadata and documentation in YAML frontmatter + Markdown
|
|
- **handler.ts**: The hook handler function (default export)
|
|
|
|
Example structure:
|
|
|
|
```
|
|
session-memory/
|
|
├── HOOK.md # Metadata + docs
|
|
└── handler.ts # Handler implementation
|
|
```
|
|
|
|
## HOOK.md Format
|
|
|
|
```yaml
|
|
---
|
|
name: my-hook
|
|
description: "Short description"
|
|
homepage: https://docs.clawd.bot/hooks/my-hook
|
|
metadata:
|
|
{ "clawdbot": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
|
|
---
|
|
# Hook Title
|
|
|
|
Documentation goes here...
|
|
```
|
|
|
|
### Metadata Fields
|
|
|
|
- **emoji**: Display emoji for CLI
|
|
- **events**: Array of events to listen for (e.g., `["command:new", "session:start"]`)
|
|
- **requires**: Optional requirements
|
|
- **bins**: Required binaries on PATH
|
|
- **anyBins**: At least one of these binaries must be present
|
|
- **env**: Required environment variables
|
|
- **config**: Required config paths (e.g., `["workspace.dir"]`)
|
|
- **os**: Required platforms (e.g., `["darwin", "linux"]`)
|
|
- **install**: Installation methods (for bundled hooks: `[{"id":"bundled","kind":"bundled"}]`)
|
|
|
|
## Creating Custom Hooks
|
|
|
|
To create your own hooks, place them in:
|
|
|
|
- **Workspace hooks**: `<workspace>/hooks/` (highest precedence)
|
|
- **Managed hooks**: `~/.clawdbot/hooks/` (shared across workspaces)
|
|
|
|
Custom hooks follow the same structure as bundled hooks.
|
|
|
|
## Managing Hooks
|
|
|
|
List all hooks:
|
|
|
|
```bash
|
|
clawdbot hooks internal list
|
|
```
|
|
|
|
Show hook details:
|
|
|
|
```bash
|
|
clawdbot hooks internal info session-memory
|
|
```
|
|
|
|
Check hook status:
|
|
|
|
```bash
|
|
clawdbot hooks internal check
|
|
```
|
|
|
|
Enable/disable:
|
|
|
|
```bash
|
|
clawdbot hooks internal enable session-memory
|
|
clawdbot hooks internal disable command-logger
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Hooks can be configured in `~/.clawdbot/clawdbot.json`:
|
|
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"internal": {
|
|
"enabled": true,
|
|
"entries": {
|
|
"session-memory": {
|
|
"enabled": true
|
|
},
|
|
"command-logger": {
|
|
"enabled": false
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Event Types
|
|
|
|
Currently supported events:
|
|
|
|
- **command**: All command events
|
|
- **command:new**: `/new` command specifically
|
|
- **command:reset**: `/reset` command
|
|
- **command:stop**: `/stop` command
|
|
|
|
More event types coming soon (session lifecycle, agent errors, etc.).
|
|
|
|
## Handler API
|
|
|
|
Hook handlers receive an `InternalHookEvent` object:
|
|
|
|
```typescript
|
|
interface InternalHookEvent {
|
|
type: "command" | "session" | "agent";
|
|
action: string; // e.g., 'new', 'reset', 'stop'
|
|
sessionKey: string;
|
|
context: Record<string, unknown>;
|
|
timestamp: Date;
|
|
messages: string[]; // Push messages here to send to user
|
|
}
|
|
```
|
|
|
|
Example handler:
|
|
|
|
```typescript
|
|
import type { InternalHookHandler } from "../../src/hooks/internal-hooks.js";
|
|
|
|
const myHandler: InternalHookHandler = async (event) => {
|
|
if (event.type !== "command" || event.action !== "new") {
|
|
return;
|
|
}
|
|
|
|
// Your logic here
|
|
console.log("New command triggered!");
|
|
|
|
// Optionally send message to user
|
|
event.messages.push("✨ Hook executed!");
|
|
};
|
|
|
|
export default myHandler;
|
|
```
|
|
|
|
## Testing
|
|
|
|
Test your hooks by:
|
|
|
|
1. Place hook in workspace hooks directory
|
|
2. Restart gateway: `pkill -9 -f 'clawdbot.*gateway' && pnpm clawdbot gateway`
|
|
3. Enable the hook: `clawdbot hooks internal enable my-hook`
|
|
4. Trigger the event (e.g., send `/new` command)
|
|
5. Check gateway logs for hook execution
|
|
|
|
## Documentation
|
|
|
|
Full documentation: https://docs.clawd.bot/internal-hooks
|