ToolCLAUDE CODE

Settings & hooks builder

Permission rules, environment variables, a default model and hooks — written into a settings.json with the exact key names and the matcher-and-handler shape the docs describe. It runs in this page; nothing is uploaded.

The builder needs JavaScript. Without it the form still shows what each field is for, and the example on the right is a working settings.json you can adapt by hand.

Scope

Which file this is

Permissions

One rule per line, written as Tool or Tool(specifier). Claude Code checks deny first, then ask, then allow, and the first match decides — a broad deny beats a narrow allow.

Allow — run without asking

Ask — always confirm, whatever the mode

Deny — block outright

Default permission mode

auto and bypassPermissions do not take effect from a project or local file — put them in your user settings.

Additional directories

One path per line. Gives file access outside the folder you started in.

Hooks

1 hook

A hook is an event, a matcher group that filters when it fires, and a handler that runs. A matcher of only letters, digits, _, -, spaces, , and | is compared as exact strings; anything else is an unanchored JavaScript regular expression.

Hook rows are built with JavaScript. The example on the right shows the shape they produce, and the cheat-sheet below lists every event and what its matcher filters.

Model, environment and the rest

Model

A model alias or a full model ID — the same value you would pass to --model. Read once, at session start.

Environment variables

KEY=VALUE, one per line. Values are plain text in the file and reach every subprocess.

Output style

The name of a built-in or custom output style. Applies after /clear or a restart.

Transcript retention (days)

cleanupPeriodDays. A whole number, 1 or more; the default is 30.

Leave the Co-Authored-By trailer off commits

Writes includeCoAuthoredBy: false, deprecated since v2.0.62 — attribution replaced it and lets you set the commit and PR text separately.

Approve every MCP server in the project .mcp.json

Writes enableAllProjectMcpServers: true. Claude Code writes this key itself when you approve all servers in the dialog.

Output

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/check-bash.sh"
          }
        ]
      }
    ]
  }
}

save as settings.json in .claude/ at your project root

Then check it

claude doctor

claude doctor lists the entries Claude Code rejected. Inside a session, /status shows which settings files loaded, /permissions shows every rule and the file it came from, and /hooks lists the hooks. Claude Code reloads permissions and hooks on save; model and outputStyle wait for a new session.

Hooks cheat-sheet

Every hook event, when it fires, and what its matcher filters. A matcher of *, an empty string, or no matcher at all fires on every occurrence — and on the events marked none a matcher is ignored entirely.

Event	Fires when	Matcher filters
`SessionStart`	A session begins or resumes	how the session started — startup, resume, clear, compact, fork
`Setup`	You start with --init-only, or with --init / --maintenance in -p mode	which CLI flag triggered setup — init, maintenance
`SessionEnd`	A session terminates	why it ended — clear, resume, logout, prompt_input_exit, other
`Notification`	Claude Code sends a notification	notification type — permission_prompt, idle_prompt, agent_needs_input, agent_completed…
`UserPromptSubmit`	You submit a prompt, before Claude processes it	none — always fires
`UserPromptExpansion`	A user-typed command expands into a prompt	command name — your skill or command names
`MessageDisplay`	While assistant message text is displayed	none — always fires
`Stop`	Claude finishes responding	none — always fires
`StopFailure`	The turn ends because of an API error	error type — rate_limit, overloaded, server_error, max_output_tokens…
`TeammateIdle`	An agent-team teammate is about to go idle	none — always fires
`PreToolUse`	Before a tool call executes — can block it	tool name — Bash, Edit\|Write, mcp__memory__.*
`PermissionRequest`	A tool call needs a permission decision	tool name — Bash, Edit\|Write, mcp__memory__.*
`PermissionDenied`	Auto mode denies a tool call	tool name — Bash, Edit\|Write, mcp__memory__.*
`PostToolUse`	After a tool call succeeds	tool name — Bash, Edit\|Write, mcp__memory__.*
`PostToolUseFailure`	After a tool call fails	tool name — Bash, Edit\|Write, mcp__memory__.*
`PostToolBatch`	After a batch of parallel tool calls resolves	none — always fires
`SubagentStart`	A subagent is spawned	agent type — general-purpose, Explore, Plan, your own agent names
`SubagentStop`	A subagent finishes	agent type — the same values as SubagentStart
`TaskCreated`	A task is being created via TaskCreate	none — always fires
`TaskCompleted`	A task is being marked as completed	none — always fires
`InstructionsLoaded`	A CLAUDE.md or .claude/rules/*.md file is loaded into context	load reason — session_start, nested_traversal, path_glob_match, include, compact
`ConfigChange`	A configuration file changes during a session	configuration source — user_settings, project_settings, local_settings, policy_settings, skills
`CwdChanged`	The working directory changes	none — always fires
`DirectoryAdded`	A directory is added mid-session via /add-dir	how it was added — slash_command, register_repo_root
`FileChanged`	A watched file changes on disk	the literal filenames to watch — .envrc\|.env
`PreCompact`	Before context compaction	what triggered it — manual, auto
`PostCompact`	After context compaction completes	what triggered it — manual, auto
`WorktreeCreate`	A worktree is being created	none — always fires
`WorktreeRemove`	A worktree is being removed	none — always fires
`PreModelSwitch`	Before Claude Code applies a model switch — can block it	the canonical name of the model being switched to
`PostModelSwitch`	After the session model changes	the canonical name of the model being switched to
`Elicitation`	An MCP server asks for your input during a tool call	MCP server name
`ElicitationResult`	After you answer an MCP elicitation	MCP server name

Source: Claude Code · Hooks · Settings reference · Configure permissions

Which file wins

When the same key is set in more than one file, the highest level that sets it wins. Lists such as permissions.allow are the exception: they merge, so each file adds entries instead of replacing another file's.

01 Managed settings Deployed by your organization. Nothing you set overrides them, apart from a few security-sensitive exceptions. highest
02 Command line — claude --settings JSON or a file you pass for one session; merged with your files key by key. one session
03 Project local — .claude/settings.local.json Yours, in this project only. Claude Code writes your “don’t ask again” approvals here and keeps the file out of git. personal
04 Shared project — .claude/settings.json Committed to the repository. Its allow rules and additional directories apply only after you accept the workspace trust dialog for that folder. the team
05 User — ~/.claude/settings.json You, in every project on this machine. On Windows that is %USERPROFILE%\.claude. lowest

Guides that use this file

All tools · MCP config generator · Everything on Claude Code commands