Hooks: from reactive to proactive
The Heartbeat handles time-based triggers ("every weekday at 9am"). Hooks handle event-based triggers ("when this happens"). Together they cover almost every workflow you will ever want.
A few useful Hooks
- PostToolUse — fires after any tool call. Use it to log every shell command for audit.
- OnTaskComplete — fires when a multi-step task ends. Send a Telegram ping with the summary.
- OnInbox — fires when a file lands in
~/inbox/. Trigger an OCR/summarize flow. - OnError — fires on any tool failure. Notify if the same error happens twice in a row.
A working "remember me" Hook
- name: ping-on-completion
on: task_complete
channel: telegram
template: |
Done: {{ task.summary }}
Spent: {{ task.duration_seconds }}s, {{ task.tokens }} tokens.
Cost: ${{ task.cost_usd }}.
This single Hook is worth the entire chapter. After installing it, your agent stops being a thing you check on and starts being a thing that reports back.
Hook hygiene
- Rate-limit your Hooks — three notifications a minute is helpful, thirty is spam
- Whitelist channels — Hooks should fire only into channels you opted in
- Test Hooks in the debug console first — there is a "fire dummy event" button for exactly this
Try it
Add the ping-on-completion Hook above. Run any non-trivial task from Telegram. Confirm you get a single, well-formatted summary message back when it is done.
