Hooks

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. Hooks are configured with a JSON format. Place them in your project’s .devin/ directory (or a user-level config) and Devin CLI runs them at the matching lifecycle events. Existing hooks in .claude/ directories are also picked up automatically — see Where Hooks Live.

What Can Hooks Do?

Enforce policies

Block dangerous commands, require confirmation for specific actions, or restrict file access.

Add context

Inject additional instructions or information when specific tools are called.

Run side effects

Execute scripts, send notifications, or log events when things happen.

Modify permissions

Dynamically grant or restrict permissions based on the situation.

Quick Example

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

{
  "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 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:

{
  "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 (see Output format below). Input (stdin):

{
  "hook_event_name": "PreToolUse",
  "tool_name": "exec",
  "tool_input": {
    "command": "rm -rf /"
  }
}

The DEVIN_PROJECT_DIR environment variable is automatically set to the project root directory. See Using the Matcher for the built-in tool names and MCP tool name format you can match.

Output format

A command hook can print a JSON object to stdout to control the outcome. To approve or block an action, return a top-level decision (with an optional reason):

{
  "decision": "block",
  "reason": "Destructive command blocked by policy"
}

To inject text into the agent’s context, return additionalContext inside a hookSpecificOutput object tagged with the event name:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Remember: deploys require an approved change ticket."
  }
}

To transparently rewrite a tool’s input before it executes, return updatedInput inside a PreToolUse hookSpecificOutput. Fields in updatedInput are merged into the tool’s arguments, so you can update a subset (e.g. just command):

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "rtk git status"
    }
  }
}

Output field	Description
`decision`	`"approve"` to allow the action, or `"block"` to deny it
`reason`	Explanation shown to the agent
`hookSpecificOutput.hookEventName`	Event the output applies to (e.g. `UserPromptSubmit`, `SessionStart`, `PreToolUse`, `PostToolUse`)
`hookSpecificOutput.additionalContext`	Text injected into the agent’s context (for `UserPromptSubmit`, `SessionStart`, `PostToolUse`)
`hookSpecificOutput.updatedInput`	Object merged into the tool’s arguments before execution (for `PreToolUse`)

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)

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.

Hooks from .claude/ paths are loaded when read_config_from.claude is enabled (the default). You can disable this in your user config if needed.

Verifying Hooks

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

/hooks

What Can Hooks Do?

Enforce policies

Add context

Run side effects

Modify permissions

Quick Example

Hook Events

Hook Format

Command Hooks

Output format

Exit Codes

Where Hooks Live

Project-Level

User-Level (Global)

Verifying Hooks

Next Steps

Lifecycle Hooks

Configuration

​What Can Hooks Do?

Enforce policies

Add context

Run side effects

Modify permissions

​Quick Example

​Hook Events

​Hook Format

​Command Hooks

​Output format

​Exit Codes

​Where Hooks Live

​Project-Level

​User-Level (Global)

​Verifying Hooks

​Next Steps

Lifecycle Hooks

Configuration

What Can Hooks Do?

Quick Example

Hook Events

Hook Format

Command Hooks

Output format

Exit Codes

Where Hooks Live

Project-Level

User-Level (Global)

Verifying Hooks

Next Steps