settings.json Guide

A detailed guide to Claude Code’s settings file system. In a harness that delegates execution authority to agents, settings.json is the file that draws the boundary of that delegation — what is auto-allowed, what requires confirmation, and what is absolutely blocked are all decided here.

Info

One-line summary: settings.json is Claude Code’s control tower. Permissions, environment variables, hooks, and security policies are managed in one place.

Claude Code uses a scope system to determine where settings apply and with whom they are shared.

When the same setting exists in multiple scopes, the more specific scope wins.

flowchart TD
    A[Setting request] --> B{Managed setting
exists?}
    B -->|Yes| C[Use Managed
Cannot be overridden]
    B -->|No| D{Local setting
exists?}
    D -->|Yes| E[Use Local
Overrides Project/User]
    D -->|No| F{Project setting
exists?}
    F -->|Yes| G[Use Project
Overrides User]
    F -->|No| H[Use User
Default]

Precedence: Managed > command-line arguments > Local > Project > User

Managed scope - use for:

• Organization-wide security policies
• Compliance requirements that cannot be overridden
• Standardized configuration deployed by IT/DevOps

User scope - use for:

• Personal settings you want in every project (theme, editor settings)
• Tools and plugins used across all projects
• API keys and authentication (stored securely)

Project scope - use for:

• Team-shared settings (permissions, hooks)
• Plugins the team should have
• Tool standardization across collaborators

Local scope - use for:

• Personal overrides in a specific project
• Testing settings before sharing with the team
• Machine-specific settings that would not work for other users

MoAI-ADK uses 4 settings file locations.

System-level locations:

• macOS: /Library/Application Support/ClaudeCode/
• Linux/WSL: /etc/claude-code/
• Windows: C:\Program Files\ClaudeCode\

Warning

Warning: .claude/settings.json is overwritten on MoAI-ADK updates. Always write personal settings in settings.local.json or ~/.claude/settings.json.

settings.json is Claude Code’s global settings file. It defines which commands are auto-allowed, which are blocked, which hooks run, and which environment variables are set.

{
  "model": "",
  "language": "",
  "attribution": {},
  "companyAnnouncements": [],
  "autoUpdatesChannel": "",
  "spinnerTipsEnabled": true,
  "terminalProgressBarEnabled": true,
  "sandbox": {},
  "hooks": {},
  "permissions": {},
  "enabledPlugins": {},
  "extraKnownMarketplaces": {},
  "fileSuggestion": {},
  "alwaysThinkingEnabled": false,
  "maxThinkingTokens": 0,
  "statusLine": {},
  "outputStyle": "",
  "cleanupPeriodDays": 30,
  "env": {}
}

Overrides the default model to use.

{
  "model": "claude-sonnet-4-5-20250929"
}

Sets Claude’s default response language.

{
  "language": "korean"
}

Supported languages: "korean", "japanese", "spanish", "french", etc.

Deletes inactive sessions older than this period at startup. Set to 0 to delete all sessions immediately. (Default: 30 days)

{
  "cleanupPeriodDays": 20
}

The release channel updates follow.

{
  "autoUpdatesChannel": "stable"
}

• "stable": about a week old, skips major regressions
• "latest" (default): the most recent release

Whether to show tips in the spinner while Claude works. Set to false to disable tips. (Default: true)

{
  "spinnerTipsEnabled": false
}

Enables the terminal progress bar showing progress in supported terminals such as Windows Terminal and iTerm2. (Default: true)

{
  "terminalProgressBarEnabled": false
}

Shows a turn-duration message after responses (e.g. “Cooked for 1m 6s”). Set to false to hide this message.

{
  "showTurnDuration": true
}

Controls whether the @ file picker respects .gitignore patterns. When true (default), files matching .gitignore patterns are excluded from suggestions.

{
  "respectGitignore": false
}

Customizes where plan files are stored. The path is relative to the project root. Default: ~/.claude/plans

{
  "plansDirectory": "./plans"
}

Manages the permissions of the commands Claude Code can run. Permission design has two goals — letting safe commands flow without confirmation so the agentic loop is never broken, and ensuring dangerous commands never get through under any circumstances.

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

The default permission mode when opening Claude Code.

Info

Note: the current MoAI-ADK settings file uses "defaultMode": "default". This may be a legacy value.

The list of commands allowed to run immediately without user confirmation.

Default allowed command categories:

allow format examples:

{
  "allow": [
    "Read",                          // tool name only
    "Bash(git add:*)",               // Bash + command pattern
    "Bash(pytest:*)",                // wildcard
    "Bash(npm run *)",               // space-separated (new format)
    "WebFetch(domain:example.com)"   // domain pattern
  ]
}

The list of commands that run after asking the user for confirmation.

{
  "ask": [
    "Bash(chmod:*)",       // change file permissions
    "Bash(chown:*)",       // change ownership
    "Bash(rm:*)",          // delete files
    "Bash(sudo:*)",        // administrator privileges
    "Read(./.env)",        // read environment variable file
    "Read(./.env.*)"       // read environment variable file
  ]
}

How ask works:

1. Claude Code attempts to run the command
2. The user is asked “Run this command?”
3. It runs if the user approves, and stops if the user declines

The list of commands that will never run under any circumstances.

Block categories:

deny format examples:

{
  "deny": [
    "Read(./secrets/**)",           // block reading the secrets directory
    "Write(~/.ssh/**)",             // block modifying SSH keys
    "Bash(git push --force:*)",     // block force push
    "Bash(rm -rf /:*)",            // block root deletion
    "Bash(DROP DATABASE:*)"        // block DB deletion
  ]
}

Additional working directories Claude can access.

{
  "permissions": {
    "additionalDirectories": [
      "../docs/"
    ]
  }
}

Prevents bypassPermissions mode from being activated. Disables the --dangerously-skip-permissions command-line flag.

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

disableBundledSkills (a boolean, or its environment-variable form) hides Claude Code’s bundled skills and workflows — e.g. /deep-research, built-in slash-command skills — from discovery, exposing only enterprise + personal + project + plugin skills. Set to true to provide a curated, bundle-free skill surface.

{
  "disableBundledSkills": true
}

The --safe-mode CLI flag applies the same runtime effect at launch time rather than in settings — useful in locked-down environments or when debugging which behavior originates from bundled skills. MoAI-ADK does not generate disableBundledSkills or pass --safe-mode automatically. Both are documented here as available options.

Permission rules follow the Tool or Tool(specifier) format. The parameter-scoped wildcard form Tool(param:value) is also supported — e.g. WebFetch(domain:example.com) allows WebFetch only for that domain, Bash(cmd:git status) matches the git status command, and * wildcards inside the value widen the match (WebFetch(domain:*.example.com), Bash(cmd:git *)). This parameter-scoped form offers finer control than the plain Tool(specifier) form. MoAI-ADK does not currently generate parameter-scoped rules in its own settings generators. The syntax is documented as an available option for projects needing parameter-level permission control.

When multiple rules match the same tool use, they are evaluated in this order.

1. Deny rules are checked first
2. Ask rules are checked second
3. Allow rules are checked last

The first matching rule determines the behavior. In other words, deny rules always take precedence over allow rules.

To match every use of a tool, use just the tool name without parentheses.

Bash(*) is identical to Bash and matches every Bash command. The two syntaxes are interchangeable.

Add a specifier in parentheses to match specific tool uses.

Bash rules support glob patterns with *. Wildcards can appear at any position — start, middle, or end of the command.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

Important: the space before * matters.

• Bash(ls *) matches ls -la but not lsof
• Bash(ls*) matches both

Legacy syntax: the :* suffix syntax (e.g. Bash(npm run:*)) is identical to * but deprecated.

Domain-specific patterns can be used with tools like WebFetch.

{
  "permissions": {
    "allow": [
      "WebFetch(domain:docs.anthropic.com)",
      "WebFetch(domain:github.com)"
    ],
    "deny": [
      "WebFetch(domain:malicious-site.com)"
    ]
  }
}

flowchart TD
    CMD["Command execution attempted"] --> CHECK_DENY{Check deny
list}

    CHECK_DENY -->|Match| BLOCK["Blocked
Never runs"]
    CHECK_DENY -->|No match| CHECK_ALLOW{Check allow
list}

    CHECK_ALLOW -->|Match| EXEC["Runs immediately"]
    CHECK_ALLOW -->|No match| CHECK_ASK{Check ask
list}

    CHECK_ASK -->|Match| ASK["User confirmation requested"]
    CHECK_ASK -->|No match| DEFAULT["Default behavior
(defaultMode)"]

    ASK -->|Approved| EXEC
    ASK -->|Declined| BLOCK

Precedence: deny > ask > allow > defaultMode

Configures advanced sandboxing behavior. Sandboxing isolates bash commands from the filesystem and network — if permission rules are the logical line of defense, the OS sandbox is the physical one.

Warning

Important: filesystem and network restrictions are configured via the Read, Edit, and WebFetch permission rules, not via sandbox settings.

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "allowUnsandboxedCommands": false,
    "network": {
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true,
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    },
    "enableWeakerNestedSandbox": false
  }
}

Claude Code adds attribution to git commits and pull requests. These are configured separately.

{
  "attribution": {
    "commit": "Custom attribution text\n\nCo-Authored-By: AI <email@example.com>",
    "pr": ""
  }
}

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Registers scripts that respond to Claude Code events.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "script path"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "security guard script path",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "formatter script path",
            "timeout": 10
          },
          {
            "type": "command",
            "command": "linter script path",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Info

For hook configuration details, see the Hooks Guide.

Plugin-related settings.

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

Controls which plugins are enabled. Format: "plugin-name@marketplace-name": true/false

Scopes:

• User settings (~/.claude/settings.json): personal plugin preferences
• Project settings (.claude/settings.json): project-specific plugins shared with the team
• Local settings (.claude/settings.local.json): machine-specific overrides (not committed)

Defines additional marketplaces to make available in the repository. Typically used in repository-level settings so team members can access the required plugin sources.

Configures a custom command for @ file-path autocompletion.

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

The built-in file suggestion uses fast filesystem traversal, but large monorepos may benefit from project-specific indexing (e.g. a prebuilt file index or a custom tool).

Extended Thinking settings. Reasoning tokens are tokens too — leaving them always on is convenient, but it is better to coordinate them with a budget.

{
  "alwaysThinkingEnabled": true,
  "maxThinkingTokens": 10000
}

Announcements displayed to users at startup. Providing multiple announcements rotates them randomly.

{
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

Configures the status line shown at the bottom of Claude Code.

{
  "statusLine": {
    "type": "command",
    "command": "bash \"$CLAUDE_PROJECT_DIR/.moai/status_line.sh\"",
    "padding": 0,
    "refreshInterval": 10
  }
}

{
  "outputStyle": "R2-D2"
}

The output style determines Claude Code’s response format. You can switch to your preferred style in settings.local.json.

The env section sets environment variables that control Claude Code’s behavior.

Info

MoAI-ADK extension: this setting is specific to MoAI-ADK and is not part of official Claude Code.

{
  "env": {
    "MOAI_CONFIG_SOURCE": "sections"
  }
}

{
  "env": {
    "ENABLE_TOOL_SEARCH": "auto:5",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
  }
}

Info

Tip: the ENABLE_TOOL_SEARCH value "auto:5" enables tool search at 5% context usage. "auto" defaults to 10%, "true" is always on, "false" always off.

ENABLE_TOOL_SEARCH controls tool search. Instead of loading all tool schemas permanently, they are searched and loaded on demand — a large context saving in environments with many servers.

{
  "permissions": {
    "allow": [
      "Bash(bun:*)",     // personally used tool
      "Bash(bun add:*)"
    ]
  },
  ],
  "outputStyle": "Mr.Alfred"  // personally preferred output style
}

Info

Settings in settings.local.json are merged into those in settings.json. On identical keys, settings.local.json wins.

From v3.0.0, settings.local.json is enforced to 0o600 (owner-only read/write) permission on creation and update. The previous 0o644 risked exposing sensitive credentials such as ANTHROPIC_AUTH_TOKEN to other local users on multi-user workstations (CWE-732 / CWE-552).

Self-audit:

# Linux
stat -c '%a' .claude/settings.local.json
# Expected: 600

# macOS
stat -f '%A' .claude/settings.local.json
# Expected: 600

If the permission is not 600, MoAI-ADK corrects it automatically at the next session start. To correct it immediately, run chmod 0600 .claude/settings.local.json.

For the detailed security model, threat analysis, and additional audit procedures, see Security Notes — CWE-732.

Info

MoAI-ADK extension: the settings in this section are specific to MoAI-ADK and are not included in the official Claude Code documentation.

MoAI-ADK provides a custom status line.

{
  "statusLine": {
    "type": "command",
    "command": "bash \"$CLAUDE_PROJECT_DIR/.moai/status_line.sh\"",
    "padding": 0,
    "refreshInterval": 10
  }
}

MoAI-ADK statusline includes the following.

• Gradient colors: dynamic color gradients based on context usage
• 5H/7D usage monitoring: 5-hour and 7-day API usage bars
• Single layout: one 3-line layout, plus a conditional session line — the former display modes all collapse to it
• Themes (defined in internal/statusline/theme.go):
  • catppuccin-mocha (default): a dark palette
  • catppuccin-latte: a light palette for bright environments

Info

Note: an unknown theme name falls back to catppuccin-mocha. The color values come from internal/tui/catppuccin.go.

The statusline theme and segments are configured in .moai/config/sections/statusline.yaml.

MoAI-ADK provides the following custom hooks.

MoAI-ADK’s hooks follow a shell-script wrapper → Go binary structure. Rather than Python/uv, for each event a .claude/hooks/moai/handle-<event>.sh wrapper forwards the stdin JSON to the moai hook <event> subcommand.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/moai/handle-session-start.sh\"",
            "timeout": 30
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/moai/handle-compact.sh\"",
            "timeout": 30
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/moai/handle-session-end.sh\"",
            "timeout": 10
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/moai/handle-pre-tool.sh\"",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/moai/handle-post-tool.sh\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Each wrapper is a thin shell script that reads the stdin JSON and passes it to the Go binary.

#!/bin/bash
# .claude/hooks/moai/handle-session-start.sh
moai hook session-start

Why shell scripts: there is no Python startup overhead (fast execution), no uv/python dependency is required, and they are cross-platform (bash, /bin/sh). The unit of a hook timeout value is seconds (not milliseconds).

{
  "outputStyle": "Mr.Alfred"
}

This style provides the distinctive response format of the Alfred AI orchestrator.

If your project uses bun, add it to settings.local.json.

{
  "permissions": {
    "allow": [
      "Bash(bun:*)",
      "Bash(bun add:*)",
      "Bash(bun remove:*)",
      "Bash(bun run:*)"
    ]
  }
}

Enable the sandbox for security, excluding Docker.

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ]
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)"
    ]
  }
}

Register a personal hook.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/my-hooks/custom_check.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <email@example.com>",
    "pr": ""
  }
}

Defines the quality-pipeline depth levels and auto-detection thresholds. The configuration surface of adaptive quality, scaling verification cost to the size of the change.

3 depth levels:

# .moai/config/sections/harness.yaml
harness:
  default_profile: "default"
  mode_defaults:
    solo: auto
    team: auto
    cg: thorough
  auto_detection:
    enabled: true
    rules:
      minimal:
        conditions:
          - "file_count <= 3 AND single_domain"
          - "spec_type in [bugfix, docs, config]"
      thorough:
        conditions:
          - "security_keywords OR payment_keywords present"
          - "spec_priority == critical"
  effort_mapping:
    minimal:  "low"
    standard: "medium"
    thorough: "high"
  levels:
    thorough:
      evaluator: true

Defines the project’s technical constraints in machine-readable form.

# .moai/config/sections/constitution.yaml
constitution:
  approved_languages: [go, typescript, python]
  approved_frameworks: [cobra, viper, gin, react, next]
  forbidden_patterns:
    - "global mutable state"
    - "panic() in library code"
  security:
    required_checks: [input-validation, sql-injection-prevention]
    forbidden_practices: ["hardcoded credentials", "HTTP without TLS"]

4 evaluator profiles are provided.

Profile file location: .moai/config/evaluator-profiles/{name}.md

• Official Claude Code settings docs - official Claude Code settings
• Hooks Guide - hook configuration details
• CLAUDE.md Guide - project instruction configuration
• IAM docs - permission system overview

Info

Tip: after changing settings, restart Claude Code for them to apply. settings.local.json is not tracked by Git, so feel free to modify it for your personal environment.