Kiro Hooks Validator (Free): Lint .kiro/hooks JSON and Find Hooks That Never Run

Find out in one command why your Kiro hook isn't firing.

Kiro Hooks Validator (Free): Lint .kiro/hooks JSON and Find Hooks That Never Run product illustration

What it does

Find out why a Kiro agent hook isn't firing. One offline Python script that lints .kiro/hooks/*.json (the v1 format used by Kiro IDE 1.0+ and CLI V3) and flags hooks that load fine but never run, run on every tool call, or loop.

Python 3.9+, standard library only, no network, no API key.

Run it

python3 tools/kiro_hooks_lint.py --project .                 # your repo's .kiro/hooks
python3 tools/kiro_hooks_lint.py --project . --global        # also ~/.kiro/hooks
python3 tools/kiro_hooks_lint.py path/to/hook.json --json    # one file, machine-readable
python3 tools/kiro_hooks_lint.py --project examples/broken   # see every check fire

Exit 0 = no errors, 1 = problems (add --strict to fail on warnings too).

What it checks

codeproblem
K121old IDE 0.x .kiro.hook files or when/then keys: IDE 1.0 shows them with an upgrade badge and doesn't run them; CLI 2.x object-form "hooks": {...}
K107 / K108old camelCase trigger names (fileEdited, agentStop, promptSubmit) in a v1 file, or a misspelled trigger (with the right name)
K123a file matcher written as a glob (src//*.ts): v1 file matchers are regexes, so it doesn't match; the fix line gives the regex
K124CLI 2.x tool names (fs_read, fs_write, execute_cmd) that V3 no longer expands
K122matcher isn't a valid regex
K115a Stop hook that runs npm test/pytest/go test directly: on Stop, exit 1 starts another agent turn, so failing tests can loop
K116an agent (prompt) action on PreToolUse/PostToolUse or an unfiltered file trigger: every match starts an agent loop and uses credits
K114 / K125a matcher on a trigger that ignores it; a tool hook with no matcher (runs on every tool call)
K110 / K111 / K112runCommand/askAgent action types, command or prompt missing
K119the command points at a script that doesn't exist (commands run in the project root)
K100-K105, K120, K126-K129invalid JSON (comments, trailing commas), version not "v1", missing name/trigger/action, duplicate names, unknown keys (with spelling hints), bad timeout/enabled, confirm blocks outside Stop
notestriggers that only run on some surfaces (SessionEnd = CLI V3 only, compaction hooks need IDE 1.4.121+/CLI 3.1.0+, file/task triggers skip Kiro Web)

Use it in CI

Copy examples/github-workflow.yml to .github/workflows/ and tools/ into your repo.

Honest limits

  • Rules follow the Kiro hooks documentation as of November 2026. It reads your files; it doesn't run Kiro, your hooks or your scripts.
  • Profile-scoped hooks inside .kiro/agents/*.json aren't linted (only the CLI 2.x object form is detected).
  • Not affiliated with Amazon Web Services or Kiro.

Format and license

Zip, 21 KB, v1.0, 20 files. Free to use, modify and share for any purpose, including commercial work, as long as this notice stays in copies. Not affiliated with Amazon Web Services or Kiro.

FAQ

Does it change my hooks?
No. It only reads them and prints problems with a fix line; --json for scripts, --strict to fail on warnings.
Does it run Kiro or my scripts?
No. It's a static check of the files against the documented v1 format.
Is it really free?
Yes, the whole tool. The paid Kiro Hooks Pack is optional.
How do I get the files?
Click Download free. The zip downloads straight away: no checkout, no account.
Do I have to sign up for the newsletter?
No. The form is optional and the download works without it.

Get Kiro Hooks Validator (Free): Lint .kiro/hooks JSON and Find Hooks That Never Run

Free Kiro hooks linter: catches old .kiro.hook files, camelCase triggers, glob matchers v1 treats as regexes, Stop-hook loops and credit-burning agent hooks.

Pairs well with

Download$119

Agent Builder Bundle

Swarm Operator Kit + x402 Builder Skills + MCP Starter Kit. $119 instead of $157.

View Agent Builder Bundle

Related