hidekazu-konishi.com

Claude Code Hooks Configuration Builder Tool - Generate and Validate Hooks for settings.json

First Published: 2026-06-24
Last Updated: 2026-06-24

Features

• Event-driven Builder: choose from the full set of current Claude Code lifecycle events (grouped by category), set a matcher, and add one or more handlers to produce a ready-to-paste hooks block.
• All five handler types: build command (shell), http (POST event data to a URL), mcp_tool (call a connected MCP tool), prompt (single-turn LLM evaluation), and agent (multi-turn, experimental) handlers, each with the right fields.
• Matcher guidance built in: the tool tells you whether each event uses a matcher, what it matches against, and the documented values - and reminds you that a value with special characters is treated as a JavaScript regular expression, while FileChanged uses literal file names.
• Validator with three severity levels: paste a config and get JSON syntax errors with line numbers, schema checks (wrong root key, event not an array, handler missing its required fields, unknown event names, unknown handler types), and security notes - each tagged as either a spec issue or a recommended practice.
• Security awareness: the Validator flags commands that look destructive and plain http:// webhook URLs, and reminds you that a clean result is not a guarantee of safety.
• Examples, copy, download, and file loading: one-click examples for common patterns, copy and download for the generated config, and drag-and-drop or file picker for the Validator input.
• 100% client-side: no requests are sent, no hook is ever run, and nothing is uploaded. Once loaded, the tool keeps working offline.

How to Use

1. Builder: optionally load an example, then for each rule pick the event, set the matcher (when the event uses one), and add handlers. Switch a handler's type to reveal that type's fields - for command, fill the command and an optional timeout; for http, the URL and any headers; and so on.
2. Generate to produce the hooks JSON, then Copy or Download it and merge it into your settings file.
3. Validator: paste or drop a .json file, click Validate, and review the Error, Warning, and Info results. Errors are structural problems; Warnings are likely mistakes; Info items are security or best-practice notes.
4. Keep secrets out of the file. Use placeholders while building and supply real tokens through environment variables that your hook command or the http handler's allowedEnvVars reads at runtime.
5. Always review hook commands. Hooks run automatically with your full permissions and no sandbox. This tool only generates and validates configuration text; it does not run hooks.

About This Tool

Claude Code hooks are shell commands (or other handlers) that Claude Code runs automatically at points in its lifecycle - before and after tool calls, when you submit a prompt, on notifications, at session start and end, and more. They live in a hooks block inside a settings file and let you enforce formatting, block risky actions, log activity, or send notifications. The hard parts are remembering the exact event names, knowing which events accept a matcher and what that matcher matches against, and getting the nested JSON shape right. This tool encodes the current event set and schema so you can generate and check a config without memorizing them.

The structure is: hooks → an event name → an array of matcher groups → each group has an optional matcher and a hooks array of handler objects → each handler has a type (command / http / mcp_tool / prompt / agent) and its type-specific fields.

Current hook events (verified against the official Claude Code documentation as of 2026-06-23):

Sources used (fetched 2026-06-23): the official Claude Code hooks reference at code.claude.com/docs/en/hooks and the hooks guide at code.claude.com/docs/en/hooks-guide. For background, see the related articles below.

Frequently Asked Questions

Which lifecycle events can I hook?

The current set is large - around thirty events spanning tool calls (PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied), prompts (UserPromptSubmit, UserPromptExpansion), session lifecycle (SessionStart, Setup, SessionEnd), the turn (Stop, StopFailure, MessageDisplay), subagents and tasks, compaction (PreCompact, PostCompact), files and config (FileChanged, ConfigChange, InstructionsLoaded, CwdChanged), notifications and MCP elicitation, and worktrees. The full table is in the About section above. The Builder lists them all, grouped by category.

How does a hook block a tool call?

For a blockable event such as PreToolUse, a hook exits with code 2 and writes a reason to stderr, which is fed back to Claude. Alternatively, a hook can exit 0 and print JSON - PreToolUse uses hookSpecificOutput.permissionDecision (one of allow, deny, ask, defer), while many other events use a top-level { "decision": "block", "reason": "..." }. Do not mix exit code 2 with JSON on stdout - when a hook exits 2, the JSON is ignored. Note that an allow decision never overrides a deny rule, and some events (such as SessionStart and Notification) cannot block at all.

Where do hooks live in settings.json?

In a hooks object, in any of the settings files: ~/.claude/settings.json (personal, all projects), .claude/settings.json (project scope, shareable), .claude/settings.local.json (gitignored), an organization-managed policy file, a plugin's hooks/hooks.json, or a skill/agent's frontmatter. Run /hooks in Claude Code to browse the merged set (it is read-only - edit the JSON to change hooks). Hooks across scopes stack rather than overriding, and a deny permission rule from any scope wins over a hook approval.

What does the matcher match against, and does it support wildcards or regex?

It depends on the event - tool events match the tool name, SessionStart matches the source, Notification matches the notification type, and so on. An empty string or * matches everything. A value containing only letters, digits, _, and | is treated as an exact string (or a |-separated list, like Edit|Write). Any other character makes Claude Code treat the whole value as a JavaScript regular expression, for example mcp__memory__.*. The one exception is FileChanged, whose matcher is literal file names separated by |, not a regex.

Are hooks safe to run?

Treat them with care. Hooks execute arbitrary shell commands with your full user permissions, automatically, with no per-execution permission dialog and no sandbox, and they receive sensitive context such as tool inputs and outputs, the working directory, and the session transcript path. Review any hook command before adding it, and be especially cautious with hooks that come from a shared config or a plugin. This tool only checks structure and common mistakes - a clean validation result is not a guarantee that a configuration is safe or that it works.

Related Tools

• MCP Server Config Builder and Validator Tool - build and validate Model Context Protocol server configurations for Claude Desktop, Claude Code, VS Code, and Cursor.
• JSON Formatter Tool - format and inspect your settings.json before or after editing.
• Regex Tester Tool - test a matcher that is treated as a JavaScript regular expression.
• Claude Code Settings and Permissions Builder and Linter Tool - build, lint, and simulate allow / deny / ask permission rules in settings.json.

Related Articles

• Claude Code Hooks Complete Guide
• Claude Code Extension Layers Decision Guide

Important Notes

• Events and syntax change over time. Claude Code hook events and configuration syntax change over time. The events and schema used here were verified against the official Claude Code documentation as of 2026-06-23. Hooks can run arbitrary commands - review any hook command before adding it. This tool only generates and validates configuration text; it does not run hooks.
• The event set is larger than older guides suggest. The current documentation lists roughly thirty events and five handler types. If a config uses an event name this tool does not recognize, the Validator raises a Warning rather than an error, because the event set can grow.
• Matcher notation is content-based. A matcher of letters, digits, _, and | is an exact-string list; anything else is a JavaScript regex. FileChanged is the exception (literal file names). The Builder and Validator apply these rules for you.
• The "agent" hook type is experimental. It is included because it is documented, but it may change. Review the official documentation before relying on it.
• Hooks run with full permissions and no sandbox. Only add hooks you understand, and be cautious with hooks from shared configs or plugins. Keep secrets out of the config file - read them from environment variables at runtime instead.
• The validator is conservative. It checks structure, the known event set, matcher notation, and required handler fields. Unknown event names or handler types produce warnings, not hard errors, and matcher values are not strictly enforced for events whose value set is not documented.