gilles/claude-code-best-practice
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f83e06eaf9fc80d28c44e6e5b4a7e54ace899a67
claude-code-best-practice/reports/claude-settings.md
T
Shayan Rais 53d4773053 [] spinnerVerbs added
2026-01-29 12:49:15 +05:00

19 KiB
Raw Blame History

Claude Code Settings Reference

A comprehensive guide to all available configuration options in Claude Code's settings.json files.

Table of Contents

  1. Settings Hierarchy
  2. Core Configuration
  3. Permissions
  4. Hooks
  5. MCP Servers
  6. Sandbox
  7. Plugins
  8. Model Configuration
  9. Display & UX
  10. AWS & Cloud Credentials
  11. Environment Variables
  12. Useful Commands

Settings Hierarchy

Claude Code uses a 4-tier configuration hierarchy (highest to lowest priority):

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.json User N/A Global personal settings
5 managed-settings.json System Read-only Organization policies

Important: Later values override earlier ones EXCEPT for:

  • deny rules (highest priority - cannot be overridden)
  • Managed settings (cannot be overridden by any local settings)

Core Configuration

General Settings

Key Type Default Description
model string "default" Override default model. Accepts aliases (sonnet, opus, haiku) or full model IDs
language string "english" Claude's preferred response language
cleanupPeriodDays number 30 Sessions inactive longer than this are deleted at startup
autoUpdatesChannel string "latest" Release channel: "stable" or "latest"
alwaysThinkingEnabled boolean false Enable extended thinking by default for all sessions

Example:

{
  "model": "opus",
  "language": "japanese",
  "cleanupPeriodDays": 60,
  "autoUpdatesChannel": "stable",
  "alwaysThinkingEnabled": true
}

Plans Directory

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

Key Type Default Description
plansDirectory string .claude/plans/ Directory where /plan outputs are stored

Example:

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

Use Case: 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.

Key Type Default Description
attribution.commit string Co-authored-by Git commit attribution (supports trailers)
attribution.pr string Generated message Pull request description attribution
includeCoAuthoredBy boolean true DEPRECATED - Use attribution instead

Example:

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: Claude <noreply@anthropic.com>",
    "pr": "Generated with Claude Code"
  }
}

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

Authentication Helpers

Scripts for dynamic authentication token generation.

Key Type Description
apiKeyHelper string Shell script path that outputs auth token (sent as X-Api-Key header)
forceLoginMethod string Restrict login to "claudeai" or "console" accounts
forceLoginOrgUUID string UUID to automatically select organization during login

Example:

{
  "apiKeyHelper": "/bin/generate_temp_api_key.sh",
  "forceLoginMethod": "console",
  "forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Company Announcements

Display custom announcements to users at startup (cycled randomly).

Key Type Description
companyAnnouncements array Array of strings displayed at startup

Example:

{
  "companyAnnouncements": [
    "Welcome to Acme Corp!",
    "Remember to run tests before committing!",
    "Check the wiki for coding standards"
  ]
}

Permissions

Control what tools and operations Claude can perform.

Permission Structure

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

Permission Keys

Key Type Description
permissions.allow array Rules allowing tool use without prompting
permissions.ask array Rules requiring user confirmation
permissions.deny array Rules blocking tool use (highest precedence)
permissions.additionalDirectories array Extra directories Claude can access
permissions.defaultMode string Default permission mode
permissions.disableBypassPermissionsMode string Prevent bypass mode activation

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

Tool Syntax Examples
Bash Bash(command pattern) Bash(npm run *), Bash(git commit *)
Read Read(path pattern) Read(.env), Read(./secrets/**)
Edit Edit(path pattern) Edit(src/**), Edit(*.ts)
Write Write(path pattern) Write(*.md), Write(./docs/**)
NotebookEdit NotebookEdit(pattern) NotebookEdit(*)
WebFetch WebFetch(domain:pattern) WebFetch(domain:example.com)
WebSearch WebSearch Global web search
Task Task(agent-name) Task(Explore), Task(my-agent)
Skill Skill(skill-name) Skill(weather-fetcher)
MCP mcp__server__tool mcp__memory__*, mcp__github__*

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 (13 total)

Event When Fired Matcher Support Common Use Cases
SessionStart New or resumed session No Load context, set environment
SessionEnd Session terminates No Cleanup, logging
UserPromptSubmit User submits prompt No Validate input, add context
PreToolUse Before tool execution Yes Validate commands, modify inputs
PostToolUse After tool succeeds Yes Run linters, verify output
PostToolUseFailure After tool fails Yes Log failures, recovery
PermissionRequest Permission dialog appears Yes Auto-approve/deny patterns
Notification Notification sent Yes Sound alerts, logging
Stop Claude finishes responding No Block/continue decisions
SubagentStart Subagent spawned Yes Per-agent setup
SubagentStop Subagent completes Yes Cleanup, validation
PreCompact Before context compaction Yes Backup, logging
Setup Repository init (--init, --maintenance) Yes One-time setup

Hook Configuration Structure

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

Hook Properties

Property Type Description
matcher string Regex pattern to match tool/event (optional)
type string "command" or "prompt"
command string Shell command to execute (for type: "command")
prompt string LLM prompt for evaluation (for type: "prompt")
timeout number Timeout in milliseconds
once boolean Run only once per session

Hook Matcher Patterns

Pattern Matches
"Bash" Exact match only
"Edit|Write" Multiple tools with regex OR
"mcp__.*" All MCP tools
"mcp__memory__.*" Specific MCP server tools
"*" or "" All tools

Hook Exit Codes

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

Environment Variables in Hooks

Variable Description
${CLAUDE_PROJECT_DIR} Project root directory
CLAUDE_TOOL_NAME Current tool name
CLAUDE_TOOL_INPUT Tool input (JSON)
CLAUDE_TOOL_OUTPUT Tool output (PostToolUse only)

Example:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/validate.py",
            "timeout": 5000
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Session started!'",
            "timeout": 1000,
            "once": true
          }
        ]
      }
    ]
  },
  "disableAllHooks": false
}

MCP Servers

Configure Model Context Protocol servers for extended capabilities.

MCP Settings

Key Type Scope Description
enableAllProjectMcpServers boolean Any Auto-approve all .mcp.json servers
enabledMcpjsonServers array Any Allowlist specific server names
disabledMcpjsonServers array Any Blocklist specific server names
allowedMcpServers array Managed only Allowlist with name/command/URL matching
deniedMcpServers array Managed only Blocklist with matching

MCP Server Matching (Managed Settings)

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": "npx @modelcontextprotocol/*" },
    { "serverUrl": "https://mcp.company.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

Example:

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

Sandbox

Configure bash command sandboxing for security.

Sandbox Settings

Key Type Default Description
sandbox.enabled boolean false Enable bash sandboxing
sandbox.autoAllowBashIfSandboxed boolean true Auto-approve bash when sandboxed
sandbox.excludedCommands array [] Commands to run outside sandbox
sandbox.allowUnsandboxedCommands boolean true Allow dangerouslyDisableSandbox
sandbox.network.allowUnixSockets array [] Unix sockets accessible in sandbox
sandbox.network.allowLocalBinding boolean false Allow binding to localhost ports (macOS)
sandbox.network.httpProxyPort number - HTTP proxy port (custom proxy)
sandbox.network.socksProxyPort number - SOCKS5 proxy port (custom proxy)
sandbox.enableWeakerNestedSandbox boolean false Weaker sandbox for Docker (reduces security)

Example:

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

Plugins

Configure Claude Code plugins and marketplaces.

Plugin Settings

Key Type Scope Description
enabledPlugins object Any Enable/disable specific plugins
extraKnownMarketplaces object Any Add custom plugin marketplaces
strictKnownMarketplaces array Managed only Allowlist of permitted marketplaces

Example:

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "experimental@acme-tools": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

Model Configuration

Model Aliases

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

Example:

{
  "model": "opus"
}

Model Environment Variables

Configure via env key:

{
  "env": {
    "ANTHROPIC_MODEL": "sonnet",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "custom-haiku-model",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "custom-sonnet-model",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "custom-opus-model",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "MAX_THINKING_TOKENS": "10000"
  }
}

Display & UX

Display Settings

Key Type Default Description
statusLine object - Custom status line configuration
outputStyle string "default" Output style (e.g., "Explanatory")
spinnerTipsEnabled boolean true Show tips while waiting
spinnerVerbs object - Custom spinner verbs with mode ("append" or "replace") and verbs array
terminalProgressBarEnabled boolean true Show progress bar in terminal
showTurnDuration boolean true Show turn duration messages
respectGitignore boolean true Respect .gitignore in file picker

Status Line Configuration

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}

File Suggestion Configuration

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  },
  "respectGitignore": true
}

Example:

{
  "statusLine": {
    "type": "command",
    "command": "git branch --show-current 2>/dev/null || echo 'no-branch'"
  },
  "spinnerTipsEnabled": false,
  "spinnerVerbs": {
    "mode": "replace",
    "verbs": ["Cooking", "Brewing", "Crafting", "Conjuring"]
  },
  "terminalProgressBarEnabled": true,
  "showTurnDuration": false
}

AWS & Cloud Credentials

AWS Settings

Key Type Description
awsAuthRefresh string Script to refresh AWS auth (modifies .aws dir)
awsCredentialExport string Script outputting JSON with AWS credentials

Example:

{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "awsCredentialExport": "/bin/generate_aws_grant.sh"
}

OpenTelemetry

Key Type Description
otelHeadersHelper string Script to generate dynamic OpenTelemetry headers

Example:

{
  "otelHeadersHelper": "/bin/generate_otel_headers.sh"
}

Environment Variables (via env)

Set environment variables for all Claude Code sessions.

{
  "env": {
    "ANTHROPIC_API_KEY": "...",
    "NODE_ENV": "development",
    "DEBUG": "true"
  }
}

Common Environment Variables

Variable Description
ANTHROPIC_API_KEY API key for authentication
ANTHROPIC_AUTH_TOKEN OAuth token
ANTHROPIC_BASE_URL Custom API endpoint
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)
CLAUDE_CODE_ENABLE_TELEMETRY Enable/disable telemetry (0 or 1)
DISABLE_ERROR_REPORTING Disable error reporting (1 to disable)
DISABLE_TELEMETRY Disable telemetry (1 to disable)
MCP_TIMEOUT MCP startup timeout in ms (default: 10000)
MAX_MCP_OUTPUT_TOKENS Max MCP output tokens (default: 50000)
BASH_MAX_TIMEOUT_MS Bash command timeout
BASH_MAX_OUTPUT_LENGTH Max bash output length
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE Auto-compact threshold percentage
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR Keep cwd between bash calls (1 to enable)
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Disable background tasks (1 to disable)
ENABLE_TOOL_SEARCH MCP tool search threshold (e.g., auto:5)
DISABLE_PROMPT_CACHING Disable all prompt caching (1 to disable)
DISABLE_PROMPT_CACHING_HAIKU Disable Haiku prompt caching
DISABLE_PROMPT_CACHING_SONNET Disable Sonnet prompt caching
DISABLE_PROMPT_CACHING_OPUS Disable Opus prompt caching

Useful Commands

Command Description
/config Interactive configuration UI
/memory View/edit all memory files
/agents Manage subagents
/mcp Manage MCP servers
/hooks View configured hooks
/plugin Manage plugins
--doctor Diagnose configuration issues
--debug Debug mode with hook execution details

Quick Reference: Complete Example

{
  "model": "sonnet",
  "language": "english",
  "cleanupPeriodDays": 30,
  "autoUpdatesChannel": "stable",
  "alwaysThinkingEnabled": true,
  "plansDirectory": "./plans",

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

  "enableAllProjectMcpServers": true,

  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Tool starting'",
            "timeout": 5000
          }
        ]
      }
    ]
  },
  "disableAllHooks": false,

  "sandbox": {
    "enabled": true,
    "excludedCommands": ["git", "docker"]
  },

  "attribution": {
    "commit": "Generated with Claude Code",
    "pr": ""
  },

  "statusLine": {
    "type": "command",
    "command": "git branch --show-current"
  },

  "spinnerTipsEnabled": true,
  "showTurnDuration": false,

  "env": {
    "NODE_ENV": "development"
  }
}

Sources

Reference in New Issue View Git Blame Copy Permalink