Claude Code — Configuration Reference

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

claude-codeconfigurationmcphookssettings

Claude Code — Configuration Reference

Claude Code configuration lives in three places: claude.json, .claude/ directory, and environment variables. Here's how to set up each one.

claude.json

Located at ~/.claude/claude.json (global) or .claude/claude.json (per-project). Project settings override global.

{
  "model": "claude-sonnet-4-20250514",
  "maxTokens": 16000,
  "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"
  },
  "tui": {
    "syntax": {
      "theme": "github-dark"
    },
    "diff": {
      "style": "unified",
      "contextLines": 5
    }
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix ${FILE_PATH}"
          }
        ]
      }
    ]
  }
}

Model Settings

KeyDescriptionDefault
modelAnthropic model IDclaude-sonnet-4-20250514
maxTokensMax output tokens per requestConfig-dependent
thinkingEnabledEnable extended thinkingfalse
thinkingBudgetExtended thinking token budget4000

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.

TUI Settings

{
  "tui": {
    "syntax": {
      "theme": "github-dark"
    },
    "diff": {
      "style": "unified",
      "contextLines": 3
    },
    "pager": "less -R"
  }
}

.claude/ Directory

Claude Code Directory Structure
.claude/
├── claude.json           # Project-specific config
├── CLAUDE.md            # Project system prompt (alternative to root CLAUDE.md)
├── settings.json        # TUI preferences
├── hooks/               # Hook scripts
│   ├── pre-tool-use/
│   └── post-tool-use/
├── mcp/                 # MCP server configs
│   └── servers.json
└── conventions/         # Additional context files
    ├── coding-style.md
    └── git-conventions.md

MCP Server Configuration

Configure MCP servers in .claude/mcp/servers.json or 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

Claude Code supports pre/post tool-use hooks. Useful for auto-linting, formatting, or validation:

Post-tool-use hook (auto-lint after file writes):

# .claude/hooks/post-tool-use/lint.sh
#!/bin/bash
if [[ "$CLAUDE_TOOL_NAME" == "Write" || "$CLAUDE_TOOL_NAME" == "Edit" ]]; then
  npx eslint --fix "$CLAUDE_TOOL_PATH"
fi

Pre-tool-use hook (warn before sensitive commands):

# .claude/hooks/pre-tool-use/warn-commit.sh
#!/bin/bash
if [[ "$CLAUDE_COMMAND" =~ ^git\ push ]]; then
  echo "⚠️  Warning: Attempting to push to remote."
  echo "    Changes should be reviewed before pushing."
  # Return non-zero to block the command
  # exit 1
fi
exit 0

Project vs Global Config

ScopePathPurpose
Global~/.claude/claude.jsonDefault settings for all projects
Project.claude/claude.jsonOverride for this specific project
Project MDCLAUDE.md or .claude/CLAUDE.mdProject-specific system prompt

Project config takes precedence over global. CLAUDE.md can exist at project root or in .claude/.

Environment Variables

VariablePurpose
ANTHROPIC_API_KEYAPI authentication (required)
ANTHROPIC_MODELOverride default model
ANTHROPIC_MAX_TOKENSMax output tokens
ANTHROPIC_BASE_URLCustom API endpoint for proxies
CLAUDE_CODE_DEBUGEnable debug logging (1 or true)