Hooks

Hooks run shell commands or agent prompts automatically when specific events happen in your session - a file is saved, a tool is invoked, or a task completes. You define the trigger and the action; Kiro handles the execution.

• Enforce standards - run linters, formatters, or type checks automatically on file save
• 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 you save 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.

Hook configurations are JSON files stored in .kiro/hooks/. 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.

See Hook Triggers for detailed descriptions, matcher patterns, and use cases for each trigger type.

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" }
    }
  ]
}

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.

• Location: .kiro/hooks/ in your project root
• Naming: Any .json filename 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 hooks array
• Activation: Hooks activate automatically when a session starts - no manual registration needed

The .kiro/hooks/*.json format was introduced in IDE 1.0 and CLI 3.0. 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 - Hooks moved from embedded fields in agent config to standalone files. Run kiro-cli agent migrate to auto-convert, or see CLI 3.0 Hooks migration for the manual 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