Hook types

Agent hooks support various trigger types, each designed for specific automation scenarios. Understanding these types helps you choose the right approach for your workflow needs.

File hooks

File hooks trigger when files matching specific glob patterns are created, saved, or deleted in your workspace. These hooks require a patterns array to specify which files to watch.

File saved

Triggers when files matching specific patterns are saved.

Use cases:

• Run linting and formatting
• Update related files
• Generate documentation
• Run tests for changed files

File created

Triggers when new files matching specific patterns are created in your workspace.

Use cases:

• Generate boilerplate code for new components
• Add license headers to new files
• Set up test files when creating implementation files

File deleted

Triggers when files matching specific patterns are deleted.

Use cases:

• Clean up related files
• Update import references in other files
• Maintain project integrity

Schema

{
  "name": "Hook Name",
  "description": "What this hook does",
  "version": "1",
  "enabled": true,
  "when": {
    "type": "fileEdited",  // or fileCreated | fileDeleted
    "patterns": ["**/*.ts", "**/*.tsx"]
  },
  "then": {
    "type": "askAgent",
    "prompt": "Your prompt here"
  }
}

Contextual hooks

Contextual hooks trigger based on agent interactions. They don't use file patterns.

Prompt submit

Triggers when the user submits a prompt.

When using the shell command action, the user prompt can be accessed via the USER_PROMPT environment variable.

Use cases:

• Provide additional context to the agent relevant to the prompt
• Block certain prompts based on their content
• Log all user prompts to a central location

Agent stop

Triggers when the agent has completed its turn and finished responding to the user.

Use cases:

• Compile code and report any failures to the agent
• Format any agent-generated code
• Review changes made by agent and provide additional instructions

Schema

{
  "name": "Hook Name",
  "description": "What this hook does",
  "version": "1",
  "enabled": true,
  "when": {
    "type": "promptSubmit"  // or agentStop
  },
  "then": {
    "type": "askAgent",     // or runCommand
    "prompt": "Your prompt here"  // or "command": "npm run build"
  }
}

Manual hooks

Manual hooks are triggered on-demand by the user. When a manual hook has a description and uses the askAgent action, it becomes available as a slash command in the chat panel using the hook's filename.

User triggered

Manually execute a hook from the Agent Hooks panel or via slash command.

Use cases:

• On-demand code reviews
• Documentation generation
• Security scanning
• Performance optimization

Schema

{
  "name": "Hook Name",
  "description": "Required for slash command",
  "version": "1",
  "enabled": true,
  "when": {
    "type": "userTriggered"
  },
  "then": {
    "type": "askAgent",
    "prompt": "Your prompt here"
  }
}

Field reference

Technical details

• Only one hook runs at a time to prevent infinite loops
• Hooks are disabled in untrusted workspaces for security
• File patterns are matched against workspace-relative paths using glob syntax
• Shell command actions are only available for promptSubmit and agentStop triggers