Hooks & Automation

You want your AI assistant to send you a Telegram message whenever a long-running agent finishes its work. Or you want to block certain tools from running without your approval. Or you want every research task to automatically save its results to a file.

Meggy's Hooks system makes this possible. Hooks are user-configurable rules that fire automatically when specific events happen — no code required. Think of them as "if this, then that" for your AI assistant.

How Hooks Work

A hook consists of two parts:

Event — What triggers the hook (e.g., "an agent finished executing")
Action — What happens when the event fires (e.g., "send a Telegram notification")

You create hooks through a simple UI that lets you pick an event, configure conditions, and choose one or more actions. Once saved, hooks run automatically in the background.

Lifecycle Events

Meggy exposes 20 lifecycle events that you can hook into:

Agent Events

Event	When It Fires
`agentStarted`	An agent begins execution
`agentCompleted`	An agent finishes successfully
`agentFailed`	An agent encounters an error
`agentSuspended`	An agent is paused
`agentResumed`	A paused agent resumes

Tool Events

Event	When It Fires
`toolCallRequested`	The AI wants to call a tool
`toolCallApproved`	A tool call was approved
`toolCallRejected`	A tool call was rejected
`toolCallCompleted`	A tool finished executing
`toolCallFailed`	A tool encountered an error

Message Events

Event	When It Fires
`messageReceived`	A new message arrives (any channel)
`messageSent`	A response is sent
`channelConnected`	A messaging channel comes online
`channelDisconnected`	A messaging channel goes offline

Device Events

Event	When It Fires
`deviceDiscovered`	A new smart device appears on the network
`deviceOnline`	A device comes back online
`deviceOffline`	A device goes offline

System Events

Event	When It Fires
`scheduledTaskRan`	A scheduled task executed
`memoryUpdated`	A new fact was stored in memory
`vaultIngested`	A new document was added to the vault

Action Types

When a hook fires, it can execute one or more of 6 action types:

Gate

Block or allow the event from proceeding. Useful for implementing safety policies.

Example: Block all terminal tool calls unless you explicitly approve them.

Log

Write event details to a log file or the system log.

Example: Log every tool call with its arguments and results for auditing.

Notify

Send a notification through a connected channel (desktop notification, Telegram, WhatsApp, Email).

Example: Send a Telegram message when an agent finishes a long research task.

Chain

Trigger another agent or action in response to the event.

Example: When a research agent completes, automatically start a summary agent on its output.

Script

Execute a shell script or Node.js snippet.

Example: Run a backup script whenever a new document is added to the vault.

Transform

Modify the event's data before it continues through the pipeline.

Example: Append a disclaimer to every outbound email message.

Real-World Examples

Here are some practical hooks you might set up:

Goal	Event	Action
Stay informed	`agentCompleted`	Notify → Send Telegram message with the result summary
Safety guardrails	`toolCallRequested` (tool = `delete_file`)	Gate → Block and ask for confirmation
Audit trail	`toolCallCompleted`	Log → Write tool name, arguments, and result to `audit.log`
Workflow chains	`agentCompleted` (agent = "Researcher")	Chain → Start "Writer" agent with the research results
Smart home alerts	`deviceOffline`	Notify → Send desktop notification
Auto-backup	`vaultIngested`	Script → Run backup script to copy vault database

Conditions and Filters

Hooks support conditions that limit when they fire:

Event filters — Only fire for specific agents, tools, or channels
Time windows — Only fire during business hours, weekends, etc.
Cooldown — Prevent a hook from firing too frequently

This lets you create precise rules without getting overwhelmed by notifications.

Getting Started

Open Settings → Hooks
Click Create Hook
Select an event from the dropdown
Configure conditions (optional)
Choose one or more actions
Save and enable

Hooks are powerful because they let your AI assistant work for you even when you're not actively using it. Set up the rules once, and Meggy follows them automatically.