Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt

Use this file to discover all available pages before exploring further.

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. If you already have hooks configured for Claude Code, they will work with Devin CLI automatically.

​
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:
EventWhen it fires
PreToolUseBefore a tool executes
PostToolUseAfter a tool finishes
PermissionRequestWhen a permission decision is needed
UserPromptSubmitWhen the user submits a message
StopWhen the agent wants to stop
SessionStartWhen a session begins
SessionEndWhen 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
        }
      ]
    }
  ]
}
FieldDescription
matcherRegex 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.
commandShell command to run (for command type).
promptLLM prompt to evaluate (for prompt type).
timeoutTimeout 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): 
{
  "hook_event_name": "PreToolUse",
  "tool_name": "exec",
  "tool_input": {
    "command": "rm -rf /"
  }
}
Output (stdout — optional): 
{
  "decision": "block",
  "reason": "Destructive command blocked by policy"
}
Output fieldDescription
decision"approve", "block", or "deny"
reasonExplanation shown to the agent
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.

​
Exit Codes

CodeMeaning
0Success — hook continues normally
2Block — action is denied
OtherError — logged but doesn’t block

​
Where Hooks Live

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

​
Project-Level

LocationDescription
.devin/hooks.v1.jsonStandalone 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)

LocationDescription
~/.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

​
Next Steps

Lifecycle Hooks

Deep dive into each event type and what data is available.

Claude Code Hooks Docs

Full reference for the hook format.