Hooks System

What are Hooks?

Hooks allow you to intercept and modify Clawdbot’s behavior at key points:

• Before a message is processed
• After Claude responds
• On errors
• During startup/shutdown

Hook Types

Pre-Message Hooks

Run before message goes to Claude:

@clawdbot.hook("pre_message")
async def filter_spam(message):
    if is_spam(message.content):
        return None  # Block message
    return message  # Continue processing

Post-Response Hooks

Run after Claude responds:

@clawdbot.hook("post_response")
async def log_response(message, response):
    logger.info(f"Response: {response.content}")
    return response

Error Hooks

Handle errors gracefully:

@clawdbot.hook("on_error")
async def handle_error(error, message):
    return "Sorry, something went wrong. Please try again."

Common Use Cases

Content Filtering

@clawdbot.hook("pre_message")
async def content_filter(message):
    # Block certain content
    if contains_blocked_content(message.content):
        return None
    return message

Rate Limiting

@clawdbot.hook("pre_message")
async def rate_limit(message):
    if is_rate_limited(message.user_id):
        await message.reply("Please slow down!")
        return None
    return message

Response Enhancement

@clawdbot.hook("post_response")
async def add_signature(message, response):
    response.content += "\n\n_Powered by Clawdbot_"
    return response

Configuration

Enable hooks in .env:

HOOKS_ENABLED=true
HOOKS_DIRECTORY=./hooks

Next Steps

• Plugin Development
• Architecture