Working with Autohand
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
Use the same hook event names across stacks, then tune the commands for the project language. The curl tab shows the notification pattern you can reuse for Slack, Discord, or any webhook receiver.
Block dangerous commands
Best practices
- Keep hooks fast. Long-running work should be marked
asyncor 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.