---
title: "Hooks"
description: "Automate actions triggered by Cody CLI events"
canonical: "https://docs.ainative.studio/docs/cody-cli/hooks"
last-updated: "2026-10-22T17:48:46.689Z"
---

# Hooks

Source: https://docs.ainative.studio/docs/cody-cli/hooks

> Automate actions triggered by Cody CLI events

# Hooks

Hooks let you run shell commands automatically in response to Cody CLI events — before/after tool calls, on session start, on file writes, and more.

## Configuration

Hooks are configured in `settings.json` under the `hooks` key:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'About to run bash tool'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "FileWrite",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CODY_TOOL_FILE_PATH"
          }
        ]
      }
    ]
  }
}
```

## Hook Events

| Event | When it fires | Can block? |
|-------|--------------|------------|
| `PreToolUse` | Before a tool runs | Yes — exit non-zero to block |
| `PostToolUse` | After a tool completes | No |
| `Notification` | When Cody sends a notification | No |
| `Stop` | When Cody finishes a turn | No |

## Matchers

Each hook entry has a `matcher` field to filter which tool it applies to:

- `Bash` — bash execution tool
- `FileWrite` — file write tool
- `FileEdit` — file edit tool
- `*` — matches all tools

## Environment Variables

Hook commands receive context via environment variables:

| Variable | Value |
|----------|-------|
| `CODY_TOOL_NAME` | Name of the tool being called |
| `CODY_TOOL_FILE_PATH` | File path (for file tools) |
| `CODY_SESSION_ID` | Current session ID |

## Example: Auto-format on write

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "FileWrite",
        "hooks": [{ "type": "command", "command": "prettier --write $CODY_TOOL_FILE_PATH 2>/dev/null || true" }]
      }
    ]
  }
}
```