Hooks

Hooks let you run custom code at key points in Mona's lifecycle. They are the event-driven backbone of MonoClaw's plugin system.

Hook events

Event	When it fires	Common uses
`pre_message`	Before Mona processes a user message	Logging, filtering, rate limiting
`post_response`	After Mona generates a response	Analytics, notifications
`pre_tool_call`	Before a tool is executed	Approval gates, logging
`post_tool_call`	After a tool returns	Result transformation, caching
`session_start`	When a new session begins	Context loading, greetings
`session_end`	When a session ends	Cleanup, summary generation
`gateway_message`	When a gateway receives a message	Routing, filtering
`cron_trigger`	When a cron job fires	Pre-job setup, validation
`error`	When an error occurs	Alerting, fallback handling

Creating hooks

As a plugin:

# my_plugin/hooks.py
from monoclaw.plugins import Hook

class SlackAlertHook(Hook):
    event = "error"

    async def run(self, error: Exception, context: dict) -> None:
        import httpx
        await httpx.AsyncClient().post(
            "https://hooks.slack.com/services/...",
            json={"text": f"Mona error: {str(error)}"}
        )

def register_hooks():
    return [SlackAlertHook()]

Inline hooks

For simple one-off hooks, use the CLI:

monoclaw hook add pre_tool_call --command "echo 'Tool: {tool_name}' >> ~/.monoclaw/logs/tools.log"

Hook ordering

Multiple hooks can fire for the same event. Control execution order:

# ~/.monoclaw/config.yaml
hooks:
  pre_message:
    - my_plugin.logging_hook    # priority: 1
    - my_plugin.filter_hook     # priority: 2

Lower numbers run first.

Hook middleware

Hooks can modify data as it passes through:

class CapitalizeHook(Hook):
    event = "post_response"

    async def run(self, response: str) -> str:
        # Transform the response
        return response.upper()

Disabling hooks

Disable specific hooks:

monoclaw hook disable my_plugin.slack_alert

Or disable all hooks for an event:

hooks:
  post_response:
    enabled: false

Best practices

Keep hooks fast — Slow hooks delay responses
Handle errors gracefully — A failing hook shouldn't crash the agent
Be selective — Don't log everything; focus on actionable events
Use async — Hooks should be async to avoid blocking
Test thoroughly — Hooks run on every matching event

Built-in hooks

MonoClaw ships with several built-in hooks:

Disk cleanup — session_end
Session analytics — session_end
Auto-save — pre_message
Security scanner — pre_tool_call

See the Built-in Plugins guide for details.