Main Configuration (settings.json)
Relevant source files
The following files were used as context for generating this wiki page:The .claude/settings.json file is the central configuration point for customizing and automating Claude Code's behavior within a project. It allows developers to define hooks that trigger custom scripts on specific events, manage environment variables, control permissions for external integrations, and enable language-specific intelligence through plugins. This file is essential for integrating Claude into a project's development lifecycle, enforcing conventions, and automating repetitive tasks.
This configuration works in tandem with other files like CLAUDE.md for persistent project memory and .mcp.json for external tool integrations. A human-readable version of the hook documentation can be found in .claude/settings.md.
Sources: README.md:11, 80-82, .claude/settings.md
Configuration Structure
The primary location for this configuration is .claude/settings.json. The system also supports a .claude/settings.local.json file, which is intended for personal overrides and should be git-ignored.
Sources: README.md:52-54
This diagram illustrates the relationship between the main configuration files.
Sources: README.md:52-56
Hooks & Environment
The most powerful feature of settings.json is the hooks object, which allows for the execution of custom commands at different points in the Claude Code lifecycle. This enables quality gates, automation, and context injection.
Sources: README.md:11, 80
Hook Events
Hooks are organized by the event that triggers them.
| Event | When It Fires | Common Use Cases |
|---|---|---|
PreToolUse | Before a tool is executed | Block edits on the main branch, validate commands |
PostToolUse | After a tool successfully completes | Auto-format code, run tests, lint files |
UserPromptSubmit | When a user submits a prompt | Add context, suggest skills, run analysis |
Stop | When the agent finishes its task | Decide if Claude should continue working |
Sources: README.md:86-94
Hook Definition
Each hook is defined by a set of properties that control its execution.
| Property | Type | Description |
|---|---|---|
matcher | string | A regex pattern that the tool name must match for the hook to run (e.g., Edit|Write). |
hooks | array | An array of hook objects to execute. |
type | string | The type of hook, typically "command". |
command | string | The shell command to execute. |
timeout | number | The maximum time in seconds the command is allowed to run. |
Sources: README.md:71-79
PreToolUse Hook Example: Block Main Branch Edits
A PreToolUse hook can act as a guardrail. The example below prevents Claude from using the Edit or Write tools when the current git branch is main.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit on main branch\"}' >&2; exit 2; }",
"timeout": 5
}
]
}
]
}
}
Sources: README.md:70-80, .claude/settings.json
The following diagram shows the flow for this hook.
Sources: README.md:70-80, 96-105
UserPromptSubmit Hook Example: Skill Evaluation
The UserPromptSubmit hook is ideal for analyzing a user's request and providing Claude with additional context. This repository uses it to power a skill evaluation system that suggests relevant skills based on the prompt content.
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/skill-eval.sh",
"timeout": 5
}
]
}
]
}
}
Sources: README.md:254-266, .claude/settings.json
This sequence diagram illustrates how the skill evaluation hook works.
Hook Response and Exit Codes
Hook scripts communicate back to Claude by writing a JSON object to stderr and using specific exit codes.
Hook Response JSON Format
| Field | Type | Description |
|---|---|---|
block | boolean | If true, blocks the action (PreToolUse only). |
message | string | A message to display to the user. |
feedback | string | Non-blocking informational feedback. |
suppressOutput | boolean | If true, hides the command's stdout. |
continue | boolean | Whether the agent should continue working. |
Exit Codes
| Code | Meaning |
|---|---|
0 | Success. |
2 | Blocking error (for PreToolUse hooks only). |
| Other | Non-blocking error. |
Sources: README.md:96-105
Plugin and Server Management
settings.json also controls the activation of LSP plugins and MCP servers.
LSP Plugins
Language Server Protocol (LSP) plugins provide Claude with real-time code intelligence, such as type information and error checking. They are enabled via the enabledPlugins key.
{
"enabledPlugins": {
"typescript-lsp@claude-plugins-official": true,
"pyright-lsp@claude-plugins-official": true
}
}
Sources: README.md:200-206
MCP Servers
Model Context Protocol (MCP) servers connect Claude to external tools like JIRA, GitHub, and Slack. These servers are defined in .mcp.json and can be automatically enabled in settings.json.
To enable all project-defined MCP servers:
{
"enableAllProjectMcpServers": true
}
To enable a specific list of servers:
{
"enabledMcpjsonServers": ["jira", "github", "slack"]
}
Sources: README.md:189-197
Summary
The .claude/settings.json file is a cornerstone of the Claude Code integration. It transforms the LLM from a simple code generator into an automated, context-aware development partner. Through its hook system, it enforces quality gates, runs tests, formats code, and injects project-specific knowledge via skill suggestions. By also managing LSP plugins and MCP servers, it ensures that Claude has a deep, real-time understanding of both the codebase and external project management tools, making it an indispensable part of a modern, automated development workflow.
Sources: README.md:9-29, 80-82, CLAUDE.md