---
title: "Hooks and Events Code"
source: https://docs.autohand.ai/working-with-autohand-code/hooks-and-events
---

# Hooks and Events

Hooks and events let you extend Autohand Code without changing the agent. Run shell commands when files change, tools run, sessions end, or errors occur. Use them to enforce quality gates, notify your team, and build audit trails.

## What hooks and events are

Hooks are shell commands that Autohand Code runs in response to **events**. Events are discrete moments in the agent lifecycle, such as a file change, a tool call, or the end of a session.

You configure hooks in JSON. The agent evaluates each event, substitutes template variables, and runs the matching commands. Commands run in order and stop on the first non-zero exit code unless you mark them asynchronous.

## Event categories

Autohand Code emits events across the whole session. The most common categories are listed below.

| Category | Example events | Use case |
|---|---|---|
| Session | on_session_start, on_session_end, on_session_resume | Initialize context and send wrap-up notifications. |
| Tool | before_tool_call, after_tool_call, on_tool_error | Log tool usage and validate results. |
| File | on_file_change, on_file_create, on_file_delete, on_file_read | Run linters, formatters, and related tests. |
| Command | before_command, after_command | Block dangerous shell commands and capture output. |
| Message | on_user_message, on_agent_response | Archive conversations and monitor token usage. |
| Error | on_error, on_permission_denied | Alert operators and write failure logs. |
| Auto-mode | on_automode_start, on_automode_stop, on_automode_iteration | Track autonomous loops and iteration counts. |
| Sub-agent | on_subagent_start, on_subagent_stop | Coordinate multi-agent workflows. |
| Notification | on_permission_request, on_notification | Surface approval requests and system alerts. |

**Tip:** Run `/hooks` in a session to list the currently configured hooks and the variables each event exposes.

## Configure hooks

Hooks live in `~/.autohand/config.json` or a project-level `.autohand/config.json`. Project-level configuration overrides user-level settings.

### Command objects

For more control, replace a plain string with an object that sets a timeout or runs asynchronously.

## Template variables

Double curly braces insert event data into commands. Available variables depend on the event type.

| Variable | Description | Events |
|---|---|---|
| {{file}} | Path to the affected file | File events |
| {{tool}} | Tool name | Tool events |
| {{command}} | Shell command text | Command events |
| {{session_id}} | Current session identifier | Session events |
| {{duration}} | Execution time in milliseconds | Session, tool, command, sub-agent events |
| {{exit_code}} | Command exit code | after_command |
| {{error}} | Error message | Error events |
| {{timestamp}} | ISO 8601 timestamp | All events |

**Tip:** Environment variables are also available in hook commands. Prefix secrets and URLs with `$` instead of embedding them in config.json.

## Common patterns

### Lint and format on save

### Run related tests

### Conditional hook with a case statement

### Block dangerous commands

## Best practices

-   Keep hooks fast. Long-running work should be marked `async` or moved to an external script.
-   Make hooks idempotent. The agent may retry an action or emit multiple file events for one logical change.
-   Exit with a non-zero status only when you want to block the underlying action. before\_tool\_call and before\_command failures can halt the agent.
-   Use environment variables for secrets and webhook URLs.
-   Test hooks outside Autohand first by copying the rendered command into your shell.