Claude Code settings.json: Complete Guide to 50+ Options

By /

Table of Contents

This single JSON file determines the behavioral boundaries of the Claude Code agent. It can block curl execution or prevent reading .env files. Most people looking for a complete Claude Code settings.json options guide share the same reason — there are over 50 configuration keys, and it’s unclear where to start.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

The major configuration keys in settings.json serve different roles by category. This guide covers the priority system, permissions, sandbox, hooks, and plugins — explaining what each key actually controls, with code examples.

settings.json 5-Tier Priority — Which Setting Wins

![settings-json-priority-layers]({{image:settings-json-priority-layers|Minimalist line art of five horizontally stacked translucent platform layers, each slightly smaller than the one below, connected by vertical dotted arrows pointing downward indicating override flow, the topmost layer glows brightest with a padlock icon, clean white background with single indigo accent color, landscape orientation, no text, no letters, no words, no characters}})

Claude Code’s configuration system isn’t a single file. It consists of 5 tiers, where higher levels override lower ones.

// Priority (high → low)
// 1. Managed (server-managed / MDM / file-based)
// 2. Command line arguments
// 3. Local (.claude/settings.local.json)
// 4. Project (.claude/settings.json)
// 5. User (~/.claude/settings.json)

There’s one critical rule: Managed settings cannot be overridden by any lower level. If an organization admin sets a command to deny at the Managed level, it stays blocked even if a developer adds it to allow at the User or Project level.

Array values are handled differently. Array-type settings like permissions.allow and sandbox.filesystem.allowWrite are merged (concatenated + deduplicated) across scopes. For example, if the User level allows Bash(git diff *) and the Project level allows Bash(npm run test *), both entries appear in the effective allow array.

Settings File Locations by Purpose
User settings (~/.claude/settings.json) serve as global defaults, Project settings (.claude/settings.json) are for team sharing, and Local settings (.claude/settings.local.json) are for personal overrides. Adding settings.local.json to .gitignore keeps personal settings out of commits.

Without understanding this structure, expect to run into "I definitely added it to allow, so why is it blocked?" scenarios. A deny at a higher level always takes precedence over an allow at a lower level.

Permissions — Evaluation Order Where deny Beats allow

![permissions-deny-allow-evaluation]({{image:permissions-deny-allow-evaluation|Technical diagram style illustration of a funnel pipeline with three sequential gate checkpoints labeled by color — red gate blocking a command arrow, yellow gate pausing it, green gate letting it pass — the red gate visually largest and positioned first, dark background with glowing neon gate indicators, landscape orientation, no text, no letters, no words, no characters}})

The permissions section is typically the first thing to configure in settings.json. It controls the agent’s tool access through three arrays: allow, ask, and deny.

{
  "permissions": {
    "allow": ["Bash(git diff *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["WebFetch", "Bash(curl *)", "Read(./.env)"]
  }
}

Rule format is Tool or Tool(specifier). Specific commands like Bash(npm run lint) can be targeted, or entire tools like WebFetch. Wildcards (*) work the same way as shell globs.

Evaluation order matters. Rules are matched in deny → ask → allow order, and the first match applies. If the same command appears in both allow and deny, deny wins.

Scenario allow deny Result
git diff Bash(git diff *) — Auto-allowed
curl request — Bash(curl *) Blocked
.env read Read(*) Read(./.env) Blocked (deny wins)
git push — (registered in ask) — Confirmation required

Domain-based filtering like WebFetch(domain:example.com) is also supported. This makes it possible to allow only specific domains while blocking all other external requests.

defaultMode Caution
Setting defaultMode to bypassPermissions or dontAsk skips all permission checks. Convenient, but risky for production projects. acceptEdits strikes a better balance — it auto-accepts code modifications while still confirming dangerous commands.

Permissions also includes additionalDirectories. This key opens up file access to directories outside the project root. It’s commonly used in monorepos to register shared package directories.

Sandbox Settings for File and Network Isolation in Claude Code settings.json

If permissions controls "which tools can be used," sandbox limits "how far those allowed tools can reach." It sets isolation boundaries along two axes: filesystem and network.

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "allowLocalBinding": true
    }
  }
}

Filesystem Isolation

The filesystem section contains four keys: allowWrite, denyWrite, denyRead, and allowRead. Three path prefix notations are supported:

  • / — absolute path
  • ~/ — relative to home directory
  • ./ — relative to project root

Adding ~/.aws/credentials to denyRead prevents the agent from reading AWS credentials. Adding /tmp/build to allowWrite permits build artifact writes while keeping other system directories blocked.

Network Isolation

Under network, allowedDomains and deniedDomains control external domain access. Wildcard subdomains (*.npmjs.org) are supported. Setting allowLocalBinding to true enables localhost binding, allowing local development server execution.

There’s also an allowUnixSockets key for controlling access to Unix sockets like Docker sockets.

Using autoAllowBashIfSandboxed
Setting autoAllowBashIfSandboxed to true eliminates the confirmation prompt for every Bash command when sandbox is enabled. The logic: since the sandbox already prevents escaping its boundaries, asking every time is unnecessary. Use excludedCommands to exclude specific commands like docker * separately.

Sandbox works across macOS, Linux, and WSL2. However, since each OS uses different sandboxing mechanisms, fine-grained path rules need per-environment testing.

Hooks and LSP-Based Token Savings Strategy

Hooks connect external scripts to Claude Code lifecycle events. Handlers are registered per event under the hooks key in settings.json. Supported events include PreToolUse, PostToolUse, and SessionStart.

From a token optimization perspective, hooks are particularly interesting. Claude Code LSP Enforcement Kit is an open-source project consisting of 5 PreToolUse hooks, 1 PostToolUse hook, and 1 SessionStart hook. When a Grep call contains code symbols (camelCase, PascalCase patterns), it forces LSP usage — replacing unnecessary full-text searches with precise symbol references.

// settings.json hook registration example
{
  "matcher": "Grep",
  "hooks": [
    {"type": "command", "command": "node ~/.claude/hooks/lsp-first-guard.js"}
  ]
}

Measured Token Reduction Results

According to this project’s measured data, approximately 235,000 tokens were saved over one week on a TypeScript project. That’s a 73–80% token reduction rate. Using LSP’s precise symbol lookups instead of broad text searches via Grep drastically reduces the amount of context included in responses.

One caveat: token optimization hooks like LSP enforcement are not covered in official documentation. Examples can only be found in community repositories, and compatibility issues may arise if Anthropic changes the hooks API.

Category Grep-based LSP-based Difference
Symbol search tokens High Low 73–80% reduction
Accuracy Text matching Syntax analysis LSP is more precise
Setup complexity None 5–7 hooks to register LSP is higher

The applications of hooks extend well beyond token optimization. Automated linting before commits, test execution after file changes, and environment variable injection at session start can all be configured through settings.json alone.

Plugins and Marketplace — enabledPlugins Configuration

Claude Code has a plugin system. The enabledPlugins key in settings.json manages activation and deactivation.

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

Plugin identifiers follow the plugin-name@marketplace-name format. true to enable, false to disable. Straightforward.

Registering a Custom Marketplace

Specifying a GitHub repository as a source in extraKnownMarketplaces enables setting up an internal marketplace. When team members trust the project folder, plugin installation from that marketplace is automatically suggested.

At the organization level, the Managed settings strictKnownMarketplaces and blockedMarketplaces come into play. Setting strictKnownMarketplaces to true blocks plugin installation from unregistered marketplaces. Adding specific marketplace names to blockedMarketplaces completely prevents using plugins from those sources.

Enterprise Plugin Management
Combining strictKnownMarketplaces: true with blockedMarketplaces in Managed settings creates an “install only from approved marketplaces” policy. These settings are typically deployed via MDM (Jamf, Intune, etc.), though practical deployment examples are only briefly covered in official documentation.

Other Essential Keys — attribution, worktree, $schema

Beyond permissions, sandbox, hooks, and plugins, settings.json contains several other keys that come up frequently in practice. Here’s a breakdown by category.

$schema and Autocompletion

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["packages/my-app", "shared/utils"]
  }
}

Setting the $schema key to https://json.schemastore.org/claude-code-settings.json enables autocompletion and inline validation in VS Code, Cursor, and similar editors. Instead of memorizing 50+ configuration keys, the editor shows candidates — reducing the need to constantly reference the Claude Code settings documentation.

worktree Settings — Large Monorepo Optimization

Specifying directories like node_modules and .cache in worktree.symlinkDirectories treats them as symbolic links during worktree creation, reducing disk usage.

worktree.sparsePaths enables checking out only specific packages in a monorepo. No need to download the entire repository, which cuts startup time. The difference is noticeable in monorepos with dozens of packages.

Customizing attribution

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

The attribution setting has two keys: commit and pr. Default values include "🤖 Generated with Claude Code" and a Co-Authored-By trailer. Setting an empty string ("") hides the attribution.

The previously used includeCoAuthoredBy key is now deprecated. It’s been replaced by directly including the Co-Authored-By line in attribution.commit.

Summary of Other Key Settings

There are over 50 major configuration keys in settings.json. Among those not covered above, here are the frequently used ones:

  • model — Default model override. Explicitly specify Sonnet, Opus, etc.
  • alwaysThinkingEnabled — Always enable Extended Thinking
  • autoUpdatesChannel — Choose between stable or latest
  • cleanupPeriodDays — Session retention period. Default is 30 days
  • effortLevel — Four tiers: low, medium, high, xhigh. A tradeoff between response quality and token consumption
  • fileSuggestion — Replace @ file autocompletion with a custom script
Choosing the Right effortLevel
low is fast but shallow in analysis, while xhigh is precise but token-heavy. For typical code reviews, medium works well. For complex refactoring or architecture analysis, high or above is more appropriate. Setting this at the Project-level settings.json based on project needs is a practical approach.

Limitations to Watch When Configuring Claude Code settings.json

A few limitations surface as settings.json usage deepens.

First, documentation on key interactions is lacking. Among 50+ keys, some can affect each other, but there’s no official guide detailing which combinations conflict. Testing is the only way to determine behavior when certain keys are set simultaneously.

Second, practical MDM deployment examples for Managed settings are scarce. Deploying managed-settings.json via Jamf or Intune is only briefly covered in official documentation. Rolling it out across hundreds of developer machines in an enterprise environment requires additional trial and error.

Third, localized documentation may lag behind. Non-English versions of the docs can be slower to reflect updates, so checking the English documentation is safer when verifying the latest keys.

No official guide currently exists that documents interaction and conflict cases across all 50+ settings.json keys. A practical approach is to rely on $schema-based editor autocompletion as new keys are added, while tracking changes through the complete Claude Code settings key documentation.

Next Steps — CLAUDE.md and MCP Server Integration

The settings covered in this Claude Code settings.json guide define the infrastructure for the agent’s behavioral boundaries. What determines how the agent behaves on top of this infrastructure is the CLAUDE.md prompt file. The standard production setup combines opening tool access via settings.json permissions while specifying coding conventions and task instructions in CLAUDE.md.

Once hooks configuration is reasonably established, MCP server integration is the next area to explore. Setting up an MCP server that connects external APIs directly to Claude Code means that settings.json permissions and sandbox rules apply equally to MCP tools. As organization scale grows, automating Managed settings deployment via MDM also becomes worth considering — though that topic warrants its own dedicated coverage on Claude Code managed settings for enterprise.

Read next

Scroll to Top