Claude Code — Configuration Reference

Complete Claude Code configuration reference. Covers settings.json files, MCP server setup, hook configuration, .claude/ directory conventions, and environment variable overrides.

October 20, 2026
claude-codeconfigurationmcphookssettings

Claude Code — Configuration Reference

Claude Code configuration lives in JSON settings files, the .claude/ directory, and environment variables. Here's how to set up each one.

Settings Files

Claude Code reads settings from ~/.claude/settings.json (user), .claude/settings.json (shared project), and .claude/settings.local.json (project local). Project settings override user settings; local settings override the shared project file.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "theme": "auto",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npx vitest *)",
      "Bash(git diff *)",
      "Bash(git status)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(git commit *)",
      "Bash(npm install *)",
      "Bash(rm *)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lint.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Model Settings

KeyDescriptionDefault
modelModel alias or full nameRuntime default (Sonnet 5.5 on the Anthropic API)
effortLevelAdaptive reasoning effort: low, medium, high, or xhighModel-dependent

Max output tokens and thinking budgets are environment variables, not settings keys. Use CLAUDE_CODE_MAX_OUTPUT_TOKENS to cap output and MAX_THINKING_TOKENS for a fixed thinking budget. Sonnet 5.5 and Opus 5.5 use adaptive reasoning controlled by /effort.

Permissions

Control what Claude Code can execute automatically:

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npx vitest *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(npm install *)",
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

Patterns support glob matching. Use * for wildcards. By default, Claude Code asks permission for each command.

Terminal Rendering

{
  "tui": "fullscreen"
}

tui accepts fullscreen or default. Switch it in a session with /tui.

.claude/ Directory

Claude Code Directory Structure
.claude/
├── settings.json        # Shared project settings
├── settings.local.json  # Personal project overrides
├── CLAUDE.md            # Project system prompt (alternative to root CLAUDE.md)
├── hooks/               # Hook scripts called by settings entries
│   └── lint.sh
└── conventions/         # Additional context files
    ├── coding-style.md
    └── git-conventions.md

MCP Server Configuration

Configure project-scoped MCP servers in .mcp.json at the project root, or add them with claude mcp add. User- and local-scoped servers live in ~/.claude.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

See the MCP Implementation Guide for Claude Code for detailed MCP setup.

Hook Scripts

Hooks are JSON entries in your settings files, not scripts discovered from a directory. Each entry names an event, a matcher, and one or more handlers. Command hooks receive the event as JSON on stdin, so read fields with jq.

PostToolUse hook (auto-lint after file writes), in .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lint.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

.claude/hooks/lint.sh:

#!/bin/bash
file=$(jq -r '.tool_input.file_path // empty')
if [ -n "$file" ]; then
  npx eslint --fix "$file"
fi

PreToolUse hook (warn before sensitive commands):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/warn-push.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

.claude/hooks/warn-push.sh:

#!/bin/bash
command=$(jq -r '.tool_input.command // empty')
if [[ "$command" =~ ^git[[:space:]]+push ]]; then
  echo "Warning: pushing to remote. Review changes first." >&2
  exit 2
fi
exit 0

Exit code 2 blocks the action. Make both scripts executable with chmod +x.

Project vs Global Config

ScopePathPurpose
User~/.claude/settings.jsonDefault settings for all projects
Project.claude/settings.jsonShared settings for this project
Project local.claude/settings.local.jsonPersonal overrides for this project
Project MDCLAUDE.md or .claude/CLAUDE.mdProject-specific system prompt

Project local settings override the shared project file, which overrides user settings. CLAUDE.md can exist at project root or in .claude/.

Environment Variables

VariablePurpose
ANTHROPIC_API_KEYAPI authentication
ANTHROPIC_MODELOverride default model
CLAUDE_CODE_MAX_OUTPUT_TOKENSMax output tokens
MAX_THINKING_TOKENSFixed extended-thinking token budget
ANTHROPIC_BASE_URLCustom API endpoint for proxies
DEBUGEnable debug logging (1), equivalent to --debug

Sources

Related Articles & Guides

Antigravity CLI — Configuration Reference

Complete configuration reference for Antigravity CLI. Settings.json, environment variables, MCP servers, plugins, trusted folders, and project context files.

Oct 20, 2026

Gemini CLI — Configuration Reference (Enterprise)

Enterprise Gemini CLI configuration reference. Covers settings.json, MCP integration, .gemini/ directory conventions, sandbox providers, extension management, and environment variables for Vertex AI deployments.

Oct 20, 2026

OpenCode — Configuration Reference

Complete OpenCode 2 configuration reference. Covers opencode.jsonc settings, providers, permissions, MCP servers, skills, plugins, and the V1 compatibility mapping.

Oct 20, 2026