Hooks

A hook is an automation with the shape when X happens, do Y, where Y is an agent prompt or a shell command. Hooks turn the chores you always mean to do, and regularly forget, into things that happen by themselves.

What is a hook?

Two halves. The trigger is an event Kiro watches for. The action is what runs when it fires. Kiro’s documented trigger types cover the moments where automation is actually useful:

• File events: save, create, delete
• Prompt submission, before your request reaches the agent
• Agent turn complete, after the agent finishes a response
• Before and after a tool invocation
• Before and after a spec task
• Manual, an on-demand button you press yourself

The action can be an agent prompt (“update the matching section in docs/api.md if this endpoint’s signature changed”) or a plain shell command. The first is flexible and costs credits; the second is deterministic and free.

Why it exists

Every codebase has a list of things that are supposed to happen and only sometimes do. The docs get updated when someone remembers. The tests get run before the commit when the commit is not urgent. The changelog gets an entry when the release is calm.

Steering does not solve this, because steering only applies when the agent is already working on something. Hooks fill the other gap: work triggered by an event rather than by a request. They are also the cleanest way to enforce a team habit without nagging, since the automation lives in the repository and applies to everyone who opens it.

How it works

Creating one. You describe the automation in plain language and Kiro writes the configuration, or you fill in a guided form in the IDE’s hook panel. IDE v1.0.242 (July 2026) added the guided form; natural-language hook generation shipped with IDE 1.0 in June 2026.

Where they live. Project hooks are files in .kiro/hooks/. User-level global hooks live in ~/.kiro/hooks/ and apply across every workspace, a feature that landed in CLI v2.13.0 and IDE v1.0.182. Kiro merges hooks across scopes rather than letting one replace the other, so a personal habit and a team rule can both run.

A worked example. Take the documentation hook that most teams want and never build. Trigger: file save, scoped to src/api/**. Action: an agent prompt reading roughly “If this endpoint’s request or response shape changed, update the matching section of docs/api.md. Do not touch anything else.” Save an endpoint, and the docs stay honest without a ticket.

The same shape covers most useful hooks. Run the test file that matches the file you just saved. Regenerate a type definition when a schema changes. Check that a new migration has a rollback. On spec-task boundaries, a before-task hook can remind the agent of a constraint, and an after-task hook can run the suite.

A note on scale. Hooks fire far more often than you expect. Saving is a reflex, not an event, and a hook attached to every save in a large repository runs dozens of times an hour. Keeping the action small is not a style preference; it is what keeps the feature usable.

Common mistakes

Heavy work on a frequent trigger. A full test suite on every save turns a two-second habit into a thirty-second wait, and within a day you will disable the hook you were so pleased with. The fix: scope the trigger to the files that matter, and run the narrowest useful check. A hook that runs tests on save should run the matching test file, not the whole suite.

A hook that triggers itself. The hook fires on save, edits a file, and the edit counts as a save. The fix: make sure the trigger pattern cannot match the files the action writes.

Forgetting that agent hooks spend credits. Kiro’s own FAQ lists agent hook execution as billable work. A chatty hook on a busy trigger is a standing bill. The fix: use a shell command where a shell command is enough, and reserve agent prompts for judgment calls.

Automating a chore nobody agreed to. A committed hook applies to your whole team, including the teammate whose editor now pauses for two seconds on every save. The fix: treat a new project hook like any other change to shared tooling and review it as one.

Permissions and safety

Hooks run actions, which means they pass through the same permission layer as anything else the agent does. A hook that runs a shell command needs the shell capability, and a deny rule beats everything: deny > ask > allow, in every scope. That ranking is the thing to remember when a hook silently does nothing. Check your permission rules before you rewrite the hook.

Where it fits

Hooks are the “when” in Kiro’s model, next to specs as the “what”, steering as the “how it thinks”, and MCP and powers as the “what it can reach”. A power can ship hooks as part of its bundle. Spec task boundaries are hook triggers, so hooks and specs interlock directly.

By surface: hooks work in the IDE, where the panel and the guided form live, and in the CLI, which supports standalone-file hooks in V3. Since September 1, 2026, hooks created in Kiro Web also sync down to local IDE and CLI sessions as read-only previews through cloud configuration sync. Kiro Crew lists hooks among its agent capabilities as well.

Learn more

• Run tests on save is the classic first hook.
• Keep docs updated with a hook is the one that pays for itself.
• Use Cases shows hooks inside larger workflows.
• Kiro CLI Guide covers hooks in the terminal.
• Common Mistakes has more on automation that backfires.