> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks

> Run custom logic when specific events occur during a session

Hooks let you run custom logic in response to events in the agent's lifecycle. You can use hooks to enforce policies, add context, log actions, modify permissions, or integrate with external systems.

Devin CLI uses a hook format that is **compatible with [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks)**. If you already have hooks configured for Claude Code, they will work with Devin CLI automatically.

***

## What Can Hooks Do?

<CardGroup cols={2}>
  <Card title="Enforce policies" icon="shield">
    Block dangerous commands, require confirmation for specific actions, or restrict file access.
  </Card>

  <Card title="Add context" icon="message">
    Inject additional instructions or information when specific tools are called.
  </Card>

  <Card title="Run side effects" icon="bolt">
    Execute scripts, send notifications, or log events when things happen.
  </Card>

  <Card title="Modify permissions" icon="lock">
    Dynamically grant or restrict permissions based on the situation.
  </Card>
</CardGroup>

***

## Quick Example

Create `.devin/hooks.v1.json` in your project:

```json theme={null}
{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/check-command.sh"
        }
      ]
    }
  ]
}
```

This runs `./scripts/check-command.sh` before every shell command execution. The script receives event data on stdin and can block the action by returning a non-zero exit code.

***

## Hook Events

Hooks can respond to these lifecycle events:

| Event               | When it fires                        |
| ------------------- | ------------------------------------ |
| `PreToolUse`        | Before a tool executes               |
| `PostToolUse`       | After a tool finishes                |
| `PermissionRequest` | When a permission decision is needed |
| `UserPromptSubmit`  | When the user submits a message      |
| `Stop`              | When the agent wants to stop         |
| `SessionStart`      | When a session begins                |
| `SessionEnd`        | When a session ends                  |

See [Lifecycle Hooks](/cli/extensibility/hooks/lifecycle-hooks) for details on each event and its available data.

***

## Hook Format

Each hook has a **type** (`command` or `prompt`), an optional **matcher** (regex on the hook event's `tool_name`), and configuration:

```json theme={null}
{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/validate.sh",
          "timeout": 10
        }
      ]
    }
  ]
}
```

| Field     | Description                                                                                                    |
| --------- | -------------------------------------------------------------------------------------------------------------- |
| `matcher` | Regex matched against the hook event's `tool_name`. Empty string or an omitted matcher matches all tool names. |
| `type`    | `"command"` to run a shell command, or `"prompt"` to evaluate an LLM prompt.                                   |
| `command` | Shell command to run (for `command` type).                                                                     |
| `prompt`  | LLM prompt to evaluate (for `prompt` type).                                                                    |
| `timeout` | Timeout in seconds (optional).                                                                                 |

### Command Hooks

Command hooks run a shell command. Event data is passed as JSON on **stdin**, and the command can return JSON on **stdout** to control the outcome.

**Input** (stdin):

```json theme={null}
{
  "hook_event_name": "PreToolUse",
  "tool_name": "exec",
  "tool_input": {
    "command": "rm -rf /"
  }
}
```

**Output** (stdout — optional):

```json theme={null}
{
  "decision": "block",
  "reason": "Destructive command blocked by policy"
}
```

| Output field | Description                         |
| ------------ | ----------------------------------- |
| `decision`   | `"approve"`, `"block"`, or `"deny"` |
| `reason`     | Explanation shown to the agent      |

The `DEVIN_PROJECT_DIR` environment variable is automatically set to the project root directory.

See [Using the Matcher](/cli/extensibility/hooks/lifecycle-hooks#using-the-matcher) for the built-in tool names and MCP tool name format you can match.

### Exit Codes

| Code  | Meaning                           |
| ----- | --------------------------------- |
| 0     | Success — hook continues normally |
| 2     | Block — action is denied          |
| Other | Error — logged but doesn't block  |

***

## Where Hooks Live

Devin CLI reads hooks from the following locations. All use the same JSON format.

### Project-Level

| Location                      | Description                                |
| ----------------------------- | ------------------------------------------ |
| `.devin/hooks.v1.json`        | Standalone hooks file (recommended)        |
| `.devin/config.json`          | `"hooks"` key in the config file           |
| `.devin/config.local.json`    | `"hooks"` key (local override, gitignored) |
| `.claude/settings.json`       | `"hooks"` key (Claude Code format)         |
| `.claude/settings.local.json` | `"hooks"` key (Claude Code format)         |

### User-Level (Global)

| Location                                                                 | Description                        |
| ------------------------------------------------------------------------ | ---------------------------------- |
| `~/.config/devin/config.json` (`%APPDATA%\devin\config.json` on Windows) | `"hooks"` key in user config       |
| `~/.claude.json`                                                         | `"hooks"` key (Claude Code format) |
| `~/.claude/settings.json`                                                | `"hooks"` key (Claude Code format) |
| `~/.claude/settings.local.json`                                          | `"hooks"` key (Claude Code format) |

<Note>
  In `.devin/hooks.v1.json`, the hooks object is the **entire file** (no wrapper key needed). In all other locations, hooks are nested under the `"hooks"` key in a settings file.
</Note>

<Note>
  Hooks from `.claude/` paths are loaded when `read_config_from.claude` is enabled (the default). You can disable this in your [user config](/cli/reference/configuration/read-config-from) if needed.
</Note>

***

## Verifying Hooks

Use the `/hooks` slash command to see all currently loaded hooks and their source files:

```
/hooks
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Lifecycle Hooks" icon="rotate" href="/cli/extensibility/hooks/lifecycle-hooks">
    Deep dive into each event type and what data is available.
  </Card>

  <Card title="Claude Code Hooks Docs" icon="arrow-up-right-from-square" href="https://docs.anthropic.com/en/docs/claude-code/hooks">
    Full reference for the hook format.
  </Card>
</CardGroup>