Kiro supports two types of hooks:
- IDE Hooks (this directory) - Standalone
.kiro.hookfiles that work in the Kiro IDE - CLI Hooks - Embedded in agent configuration files for CLI usage
IDE hooks are .kiro.hook files in .kiro/hooks/ that appear in the Agent Hooks panel in the Kiro IDE.
{
"version": "1.0.0",
"enabled": true,
"name": "hook-name",
"description": "What this hook does",
"when": {
"type": "fileEdited",
"patterns": ["*.ts", "*.tsx"]
},
"then": {
"type": "runCommand",
"command": "npx tsc --noEmit",
"timeout": 30
}
}version- Hook version (e.g., "1.0.0")enabled- Whether the hook is active (true/false)name- Hook identifier (kebab-case)description- Human-readable descriptionwhen- Trigger configurationthen- Action to perform
fileEdited- When a file matching patterns is editedfileCreated- When a file matching patterns is createdfileDeleted- When a file matching patterns is deleteduserTriggered- Manual trigger from Agent Hooks panelpromptSubmit- When user submits a promptagentStop- When agent finishes respondingpreToolUse- Before a tool is executed (requirestoolTypes)postToolUse- After a tool is executed (requirestoolTypes)
runCommand- Execute a shell command- Optional
timeoutfield (in seconds)
- Optional
askAgent- Send a prompt to the agent
When hooks run, these environment variables are available:
$KIRO_HOOK_FILE- Path to the file that triggered the hook (for file events)
CLI hooks are embedded in agent configuration files (.kiro/agents/*.json) for use with kiro-cli.
{
"name": "my-agent",
"hooks": {
"agentSpawn": [
{
"command": "git status"
}
],
"postToolUse": [
{
"matcher": "fs_write",
"command": "npx tsc --noEmit"
}
]
}
}See .kiro/agents/tdd-guide-with-hooks.json for a complete example.
- IDE Hooks: https://kiro.dev/docs/hooks/
- CLI Hooks: https://kiro.dev/docs/cli/hooks/