Claude Code Settings Reference - Claude Code Best Practice

A comprehensive guide to all available configuration options in Claude Code’s settings.json files. As of February 2026, Claude Code exposes 38 settings and 84 environment variables (use the "env" field in settings.json to avoid wrapper scripts).

Settings Hierarchy

Claude Code settings use a 5-level user-writable override chain plus an enforced policy layer:

Priority	Location	Scope	Version Control	Purpose
1	Command line arguments	Session	N/A	Single-session overrides
2	`.claude/settings.local.json`	Project	No (git-ignored)	Personal project-specific
3	`.claude/settings.json`	Project	Yes (committed)	Team-shared settings
4	`~/.claude/settings.local.json`	User	N/A	Personal global overrides
5	`~/.claude/settings.json`	User	N/A	Global personal defaults

Policy layer: managed-settings.json is organization-enforced and cannot be overridden by local settings.

deny rules have highest safety precedence and cannot be overridden by lower-priority allow/ask rules.
Managed settings may lock or override local behavior even if local files specify different values.

Core Configuration

General Settings

model

string

default:"default"

Override default model. Accepts aliases (sonnet, opus, haiku) or full model IDs

agent

string

Set the default agent for the main conversation. Value is the agent name from .claude/agents/. Also available via --agent CLI flag

language

string

default:"english"

Claude’s preferred response language

cleanupPeriodDays

number

default:30

Sessions inactive longer than this are deleted at startup

autoUpdatesChannel

string

default:"latest"

Release channel: "stable" or "latest"

alwaysThinkingEnabled

boolean

default:false

Enable extended thinking by default for all sessions

skipWebFetchPreflight

boolean

default:false

Skip WebFetch blocklist check before fetching URLs

Example:

{
  "model": "opus",
  "agent": "code-reviewer",
  "language": "japanese",
  "cleanupPeriodDays": 60,
  "autoUpdatesChannel": "stable",
  "alwaysThinkingEnabled": true
}

Plans Directory

Store plan files in a custom location relative to project root.

plansDirectory

string

default:".claude/plans/"

Directory where /plan outputs are stored

Example:

{
  "plansDirectory": "./my-plans"
}

Useful for organizing planning artifacts separately from Claude’s internal files, or for keeping plans in a shared team location.

Attribution Settings

Customize attribution messages for git commits and pull requests.

attribution.commit

string

default:"Co-authored-by"

Git commit attribution (supports trailers)

attribution.pr

string

Pull request description attribution

includeCoAuthoredBy

boolean

default:true

DEPRECATED - Use attribution instead

Example:

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: Claude <[email protected]>",
    "pr": "Generated with Claude Code"
  }
}

Set to empty string ("") to hide attribution entirely.

Permissions

Control what tools and operations Claude can perform.

Permission Structure

{
  "permissions": {
    "allow": [],
    "ask": [],
    "deny": [],
    "additionalDirectories": [],
    "defaultMode": "acceptEdits",
    "disableBypassPermissionsMode": "disable"
  }
}

Permission Modes

Mode	Behavior
`"default"`	Standard permission checking with prompts
`"acceptEdits"`	Auto-accept file edits without asking
`"askEdits"`	Ask before every operation
`"viewOnly"`	Read-only mode, no modifications
`"bypassPermissions"`	Skip all permission checks (dangerous)
`"plan"`	Read-only exploration mode

Tool Permission Syntax

Bash
File Operations
MCP
Other Tools

"Bash(npm run *)"
"Bash(* install)"
"Bash(git * main)"

Wildcards can appear at any position

"Read(.env)"
"Edit(src/**)"
"Write(*.md)"

Supports glob patterns

"mcp__*"
"mcp__memory__*"
"mcp__github__create_issue"

Format: mcp__server__tool

"WebFetch(domain:example.com)"
"Task(agent-name)"
"Skill(skill-name)"

Example:

{
  "permissions": {
    "allow": [
      "Edit(*)",
      "Write(*)",
      "Bash(npm run *)",
      "Bash(git *)",
      "WebFetch(domain:*)",
      "mcp__*"
    ],
    "ask": [
      "Bash(rm *)",
      "Bash(git push *)"
    ],
    "deny": [
      "Read(.env)",
      "Read(./secrets/**)",
      "Bash(curl *)"
    ],
    "additionalDirectories": ["../shared-libs/"]
  }
}

Hooks

Execute custom shell commands at various points in Claude Code’s lifecycle.

Hook Events (16 total)

SessionStart

When: New or resumed sessionMatcher Support: NoUse Cases: Load context, set environment

SessionEnd

When: Session terminatesMatcher Support: NoUse Cases: Cleanup, logging

PreToolUse

When: Before tool executionMatcher Support: YesUse Cases: Validate commands, modify inputs

PostToolUse

When: After tool succeedsMatcher Support: YesUse Cases: Run linters, verify output

Stop

When: Claude finishes respondingMatcher Support: NoUse Cases: Block/continue decisions

SubagentStart

When: Subagent spawnedMatcher Support: YesUse Cases: Per-agent setup

SubagentStop

When: Subagent completesMatcher Support: YesUse Cases: Cleanup, validation

Hook Configuration Structure

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "script.sh",
            "timeout": 60000,
            "once": true
          }
        ]
      }
    ]
  },
  "disableAllHooks": false
}

Hook Exit Codes

Exit Code	Behavior
`0`	Success, continue
`1`	Error (logged, continues)
`2`	Block the operation

MCP Servers

Configure Model Context Protocol servers for extended capabilities.

enableAllProjectMcpServers

boolean

Auto-approve all .mcp.json servers

enabledMcpjsonServers

array

Allowlist specific server names

disabledMcpjsonServers

array

Blocklist specific server names

Example:

{
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["memory", "github", "filesystem"],
  "disabledMcpjsonServers": ["experimental-server"]
}

Sandbox

Configure bash command sandboxing for security.

sandbox.enabled

boolean

default:false

Enable bash sandboxing

sandbox.autoAllowBashIfSandboxed

boolean

default:true

Auto-approve bash when sandboxed

sandbox.excludedCommands

array

default:[]

Commands to run outside sandbox

sandbox.network.allowUnixSockets

array

default:[]

Specific Unix socket paths accessible in sandbox

sandbox.network.allowLocalBinding

boolean

default:false

Allow binding to localhost ports (macOS)

Example:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker", "gh"],
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  }
}

Model Configuration

Model Aliases

Alias	Description
`"default"`	Recommended for your account type
`"sonnet"`	Latest Sonnet model (Claude Sonnet 4.6)
`"opus"`	Latest Opus model (Claude Opus 4.6)
`"haiku"`	Fast Haiku model
`"sonnet[1m]"`	Sonnet with 1M token context
`"opusplan"`	Opus for planning, Sonnet for execution

Effort Level (Opus 4.6)

When Opus 4.6 is selected, the /model command exposes an effort level control that adjusts how much reasoning the model applies per response.

Effort Level	Description
High (default)	Full reasoning depth, best for complex tasks
Medium	Balanced reasoning, good for everyday tasks
Low	Minimal reasoning, fastest responses

Run /model in Claude Code, select Default (recommended) — Opus 4.6, then use ← → arrow keys to adjust the effort level.

Display & UX

Display Settings

statusLine

object

Custom status line configuration

outputStyle

string

default:"default"

Output style (e.g., "Explanatory")

spinnerTipsEnabled

boolean

default:true

Show tips while waiting

terminalProgressBarEnabled

boolean

default:true

Show progress bar in terminal

showTurnDuration

boolean

default:true

Show turn duration messages

respectGitignore

boolean

default:true

Respect .gitignore in file picker

Example:

{
  "statusLine": {
    "type": "command",
    "command": "git branch --show-current"
  },
  "spinnerTipsEnabled": true,
  "terminalProgressBarEnabled": true,
  "showTurnDuration": false
}

Environment Variables (via `env`)

Set environment variables for all Claude Code sessions.

{
  "env": {
    "ANTHROPIC_API_KEY": "...",
    "NODE_ENV": "development",
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
  }
}

Common Environment Variables

Authentication

ANTHROPIC_API_KEY — API key for authentication
ANTHROPIC_AUTH_TOKEN — OAuth token
ANTHROPIC_BASE_URL — Custom API endpoint

Cloud Providers

CLAUDE_CODE_USE_BEDROCK — Use AWS Bedrock (1 to enable)
CLAUDE_CODE_USE_VERTEX — Use Google Vertex AI (1 to enable)
CLAUDE_CODE_USE_FOUNDRY — Use Microsoft Foundry (1 to enable)

Context & Compaction

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE — Auto-compact threshold percentage (1-100). Default is ~95%. Set lower (e.g., 50) to trigger compaction earlier
MAX_THINKING_TOKENS — Limit thinking token budget (set to 0 to disable)

MCP

MCP_TIMEOUT — MCP startup timeout in ms (default: 10000)
MAX_MCP_OUTPUT_TOKENS — Max MCP output tokens (default: 50000)
ENABLE_TOOL_SEARCH — MCP tool search threshold (e.g., auto:5)

Useful Commands

/model

Switch models and adjust Opus 4.6 effort level

/config

Interactive configuration UI

/memory

View/edit all memory files

/agents

Manage subagents

/mcp

Manage MCP servers

/hooks

View configured hooks

/plugin

Manage plugins

/permissions

View and manage permission rules

--doctor

Diagnose configuration issues

Sources

Settings Documentation

Official Claude Code settings reference

Settings JSON Schema

Complete schema definition

Configuration Guide

ClaudeLog configuration guide

GitHub Examples

Community settings examples

Get Started

Core Concepts

Best Practices

Workflows & Patterns

Implementation Examples

​Settings Hierarchy

​Core Configuration

​General Settings

​Plans Directory

​Attribution Settings

​Permissions

​Permission Structure

​Permission Modes

​Tool Permission Syntax

​Hooks

​Hook Events (16 total)

​Hook Configuration Structure

​Hook Exit Codes

​MCP Servers

​Sandbox

​Model Configuration

​Model Aliases

​Effort Level (Opus 4.6)

​Display & UX

​Display Settings

​Environment Variables (via env)

​Common Environment Variables

​Useful Commands

/model

/config

/memory

/agents

/mcp

/hooks

/plugin

/permissions

--doctor

​Sources

Settings Documentation

Settings JSON Schema

Configuration Guide

GitHub Examples

Build docs developers (and LLMs) love

Settings Hierarchy

Core Configuration

General Settings

Plans Directory

Attribution Settings

Permissions

Permission Structure

Permission Modes

Tool Permission Syntax

Hooks

Hook Events (16 total)

Hook Configuration Structure

Hook Exit Codes

MCP Servers

Sandbox

Model Configuration

Model Aliases

Effort Level (Opus 4.6)

Display & UX

Display Settings

Environment Variables (via `env`)

Common Environment Variables

Useful Commands

Sources