Hooks run shell commands or agent prompts automatically when specific events happen in your session - the agent modifies a file, invokes a tool, or completes a task. You define the trigger and the action; Kiro handles the execution.
| Capability | IDE | CLI | Web | Mobile |
|---|---|---|---|---|
| Event-driven hooks | ✓ | ✓ | ✓ | — |
| Shell command actions | ✓ | ✓ | ✓ | — |
| Agent prompt actions | ✓ | ✓ | ✓ | — |
| Create Hooks by asking the agent in chat | ✓ | ✓ | ✓ | — |
- Enforce standards - run linters, formatters, or type checks automatically after agent file changes
- Gate dangerous operations - block tool execution unless preconditions are met (PreToolUse)
- Generate companion files - auto-create tests, docs, or translations when new source files appear
- Validate before commit - check code quality before the agent finalizes changes
- Inject context - feed the agent additional instructions based on what it's doing
A PostFileSave hook that runs ESLint whenever the agent saves or edits a TypeScript file:
{ "version": "v1", "hooks": [{ "name": "Lint on save", "trigger": "PostFileSave", "matcher": "\\.(ts|tsx)$", "action": { "type": "command", "command": "npx eslint --fix" } }] }
This file lives at .kiro/hooks/lint-on-save.json and activates automatically - no manual prompting needed. The hook receives the saved file path and session context via STDIN. See Hook Actions for details on how commands receive event data.
Project Hook configurations are JSON files stored in .kiro/hooks/. Kiro CLI V3 also loads global Hooks from ~/.kiro/hooks/, so one Hook can run across every workspace. Global and workspace Hooks run alongside each other. Each file defines one or more Hooks with a trigger event, an optional matcher pattern, and an action.
When the trigger event fires, Kiro checks the matcher. If it matches (or no matcher is specified), the action executes:
- Command actions run a shell command in your project root. The command receives session context as JSON on STDIN.
- Agent actions inject a prompt into the current conversation, steering the agent's behavior.
Use Hook types to choose the trigger for your task. It is the authoritative trigger list and documents surface availability and trigger-specific behavior.
Each hook file is a standalone JSON file at .kiro/hooks/<id>.json. The full schema:
{ "version": "v1", "hooks": [ { "name": "example-hook", "trigger": "PostFileSave", "matcher": "\\.(ts|tsx)$", "action": { "type": "command", "command": "npx eslint --fix" } } ] }
| Field | Required | Description |
|---|---|---|
version | Yes | Schema version - currently "v1" |
hooks | Yes | Array of hook definitions |
hooks[].name | Yes | Human-readable identifier for the hook |
hooks[].description | No | Documentation only |
hooks[].trigger | Yes | Event that fires the hook (PascalCase - see Hook types) |
hooks[].matcher | No | Filters which events fire this hook. For PreToolUse/PostToolUse, a tool selector (tool ID, category tag, @mcp, @<server>, or wildcard) or a regex against the tool ID; see Hook types. For file events, a regex against the file path. Defaults to always-match. |
hooks[].action.type | Yes | "command" (shell command) or "agent" (inject prompt) |
hooks[].action.command | Cond. | Shell command to run (required when type is "command") |
hooks[].action.prompt | Cond. | Prompt text to inject (required when type is "agent") |
hooks[].timeout | No | Timeout in seconds for command actions (default: 60). 0 disables the timeout. Ignored for agent actions. |
hooks[].enabled | No | Set false to skip the hook without deleting it (default: true) |
hooks[].confirm | No | Ask for confirmation before a Stop command hook runs. See Confirmation prompts. |
A command hook on the Stop trigger can ask before it runs. Add a confirm block with the question to ask and the options to present:
{ "version": "v1", "hooks": [ { "name": "Submit session results", "trigger": "Stop", "action": { "type": "command", "command": "./submit.sh" }, "confirm": { "question": "Submit this session's results?", "options": [ { "id": "submit", "label": "Yes, submit", "run": true }, { "id": "dismiss", "label": "Not this time", "run": false } ] } } ] }
Each option has an id, a label shown on the button, and a run flag that controls whether the hook's command executes when that option is chosen.
To decide at run time whether and what to ask, add an optional confirmCommand to the confirm block. The command runs before the prompt appears, and its stdout controls the prompt as JSON:
{ "skip": true }suppresses the prompt and skips the hook for this turn{ "question": "...", "options": [...] }replaces the static question and options
{ "confirm": { "question": "Submit this session's results?", "confirmCommand": "./confirm-options.sh", "options": [ { "id": "submit", "label": "Yes, submit", "run": true }, { "id": "dismiss", "label": "Not this time", "run": false } ] } }
If confirmCommand exits non-zero, times out, or prints invalid JSON, the static question and options are used as a fallback. This makes it useful for prompts that should only appear under certain conditions - for example, a "don't ask again this session" option that writes a marker file and returns { "skip": true } on later turns.
- Workspace location:
.kiro/hooks/in your project root - Global location (CLI V3):
~/.kiro/hooks/for Hooks that run in every workspace - Naming: Any
.jsonfilename works - use descriptive kebab-case names (e.g.,lint-on-save.json,guard-writes.json) - Multiple Hooks per file: A single file can define multiple Hooks in the
hooksarray - Activation: Hooks activate automatically when a session starts - no manual registration needed
Click the + button in the Agent Hooks section of the Kiro panel and select Ask Kiro to create a hook. Describe what you want in natural language - for example, "run tests after every file save" - and Kiro generates the hook configuration through conversation.
The resulting hook is saved as a JSON file in .kiro/hooks/.
The .kiro/hooks/*.json format was introduced in IDE 1.0 and CLI V3. If you're upgrading from an earlier version:
- From IDE 0.x - Hooks moved from the previous format to standalone JSON files with PascalCase trigger names. See What's new in IDE 1.0: Hooks for the trigger mapping.
- From CLI 2.x - Run
/upgrade-agentto convert object-form Hooks into a profile-scoped array. Move definitions that should run independently of a profile or across surfaces into standalone.kiro/hooks/*.jsonfiles. See CLI V3 Hooks migration for both current placements and the trigger mapping.
- Hook Triggers - Trigger types and their use cases
- Hook Actions - Command and agent action details
- Management - Organize, edit, and maintain hooks
- Best Practices - Patterns for effective hook design
- Examples - Templates you can use
- Troubleshooting - Common issues and solutions
Hooks