Skip to content
AgentAtlas

Kiro Hooks: .kiro/hooks JSON, PreToolUse, PostFileSave and Stop

How do I set up hooks in Kiro?

Create a JSON file in .kiro/hooks/ with a version of v1 and a hooks array. Each hook has a name, a trigger such as PostFileSave or PreToolUse, an optional matcher and an action that runs a shell command or injects an agent prompt. Hooks activate automatically when a session starts.

Compare: hooks in every AI coding agent →

Where hook files go

  • Workspace: .kiro/hooks/ in your project root
  • Global (CLI V3): ~/.kiro/hooks/
  • Any .json filename works, and one file can hold several hooks.

In the IDE you can also click + in the Agent Hooks section of the Kiro panel and pick Ask Kiro to create a hook.

Lint after the agent edits a file

.kiro/hooks/lint-on-save.json

{
  "version": "v1",
  "hooks": [{
    "name": "Lint on save",
    "trigger": "PostFileSave",
    "matcher": "\\.(ts|tsx)$",
    "action": { "type": "command", "command": "npx eslint --fix" }
  }]
}

Hook fields

  • name and trigger: required. Triggers use PascalCase.
  • matcher: for file events, a regex on the file path. For PreToolUse and PostToolUse, a tool ID, a category like shell or write, @mcp, @<server> or a regex.
  • action.type: command or agent. Use action.command or action.prompt.
  • timeout: seconds for command actions. 0 disables it.
  • enabled: set to false to skip a hook without deleting it.

Triggers you can use

  • UserPromptSubmit (Prompt Submit)
  • Stop (Agent Stop)
  • SessionStart and SessionEnd (SessionEnd is CLI V3 only)
  • PreToolUse and PostToolUse
  • PostFileSave, plus File Create and File Delete events
  • PreTaskExec for spec tasks

Block a tool call

Command hooks get event data as JSON on STDIN. On exit code 0, output can be added to context. In the CLI, exit code 2 blocks PreToolUse. In the IDE, any non-zero exit blocks a Pre Tool Use hook.

.kiro/hooks/guard-shell.json

{
  "version": "v1",
  "hooks": [{
    "name": "Guard shell commands",
    "trigger": "PreToolUse",
    "matcher": "shell",
    "action": { "type": "command", "command": "./scripts/guard.sh" }
  }]
}

Agent prompt actions use credits because they start a new agent loop. Shell command actions do not.

Sources

More Kiro guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →