Claude Code Research

Configuration Reference

6 min read

Configuration Reference

Tags: claude-code configuration settings hooks reference

This guide consolidates all configuration options for Claude Code, including settings, hooks, and environment configuration.

Table of Contents

Configuration Files

File Locations and Priority

Claude Code uses a hierarchical configuration system:

  1. User-level: ~/.claude/settings.json - Global settings
  2. Project-level: .claude/settings.json - Shared project settings
  3. Local overrides: .claude/settings.local.json - Local, untracked settings

Settings are merged with local overrides taking precedence over project settings, which take precedence over user settings.

Authentication Configuration

export ANTHROPIC_API_KEY="your-api-key-here"

Method 2: Configuration File

~/.config/claude/settings.json:

{
  "api_key": "your-api-key-here"
}

Settings Structure

Complete Settings Template

{
  "api_key": "your-api-key-here",
  "model": "claude-sonnet-4-20250514",
  "permission_mode": "cautious",
  "max_turns": 3,
  "working_directory": "/path/to/project",
  "system_prompt": "You are a helpful assistant",
  "hooks": {
    // Hook configurations (see Hooks Configuration section)
  },
  "mcp_servers": {
    // MCP server configurations (see MCP Configuration section)
  }
}

Core Settings

SettingTypeDefaultDescription
api_keystring-Your Anthropic API key
modelstringclaude-sonnet-4-20250514Model to use
permission_modestringcautiousFile operation permission mode
max_turnsnumber3Maximum conversation turns
working_directorystringCurrent directoryDefault working directory
system_promptstring-Custom system prompt

Permission Modes

  • strict: Requires explicit confirmation for all file operations
  • cautious: Asks for confirmation on potentially destructive operations (default)
  • relaxed: Minimal confirmations, suitable for trusted environments

Available Models

  • claude-sonnet-4-20250514 - Default balanced model
  • claude-haiku-4-20250514 - Faster, lightweight model
  • claude-opus-4-20250514 - Most capable model

Hooks Configuration

Hook Events Overview

EventWhen It FiresCan Block?Common Use Cases
PreToolUseBefore tool execution✅ Yes (exit 2)Validation, security checks
PostToolUseAfter tool success❌ NoFormatting, logging, notifications
UserPromptSubmitUser submits prompt✅ YesInput validation, preprocessing
NotificationClaude sends notification❌ NoCustom alerts, logging
StopMain agent finishes❌ NoCleanup, commits, summaries
SubagentStopSubagent completes❌ NoTask tracking, logging
PreCompactBefore context compaction❌ NoContext management

Hook Configuration Structure

{
  "hooks": {
    "EVENT_NAME": [
      {
        "matcher": "TOOL_PATTERN",
        "hooks": [
          {
            "type": "command",
            "command": "YOUR_COMMAND",
            "timeout": 30000
          }
        ]
      }
    ]
  }
}

Hook Matcher Patterns

PatternMatchesExample
.*All toolsUniversal hooks
Edit|WriteMultiple toolsFile modifications
^Bash$Exact matchOnly Bash tool
mcp__.*MCP toolsAll MCP integrations

Complete Hooks Example

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/validation-script.sh",
            "timeout": 30000
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_FILE_PATHS",
            "timeout": 10000
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Task completed'",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Hook Environment Variables

Variables available to hook scripts:

  • $CLAUDE_TOOL_NAME - Name of the tool being executed
  • $CLAUDE_TOOL_INPUT - Input parameters passed to the tool
  • $CLAUDE_TOOL_OUTPUT - Tool’s output (PostToolUse only)
  • $CLAUDE_FILE_PATHS - Space-separated list of relevant file paths
  • $CLAUDE_NOTIFICATION - Notification message content

Hook Input Structure

Hooks receive JSON input via stdin:

{
  "session_id": "unique-session-id",
  "transcript_path": "/path/to/conversation.json",
  "cwd": "/current/working/directory",
  "hook_event_name": "PreToolUse",
  "tool_name": "Edit",
  "tool_input": {
    "file_path": "/path/to/file",
    "old_string": "original",
    "new_string": "modified"
  }
}

Hook Exit Codes

CodeEffectUse Case
0Continue normallySuccess
2Block operationValidation failure (PreToolUse only)
OtherWarning, continueNon-critical errors

Environment Variables

Claude Code Environment Variables

VariableDescriptionExample
ANTHROPIC_API_KEYAPI authentication keysk-ant-...
CLAUDE_MODELOverride default modelclaude-opus-4-20250514
CLAUDE_PERMISSION_MODEOverride permission moderelaxed
CLAUDE_WORKING_DIROverride working directory/home/user/project
CLAUDE_MAX_TURNSOverride max turns5
CLAUDE_DEBUGEnable debug loggingtrue

Development Environment

.env file example:

ANTHROPIC_API_KEY=your-api-key
NODE_ENV=development
CLAUDE_DEBUG=true
CLAUDE_MODEL=claude-haiku-4-20250514

MCP Configuration

Claude Desktop Configuration

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "my-tools": {
      "command": "node",
      "args": ["/path/to/your/mcp-server.js"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb",
        "API_KEY": "your-api-key"
      }
    },
    "file-tools": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "github-tools": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

MCP Server Configuration Options

FieldTypeDescription
commandstringCommand to start the server
argsstring[]Command arguments
envobjectEnvironment variables for the server
cwdstringWorking directory (optional)

TypeScript Configuration

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "lib": ["ES2022"],
    "types": ["node"],
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Package.json Configuration

{
  "name": "claude-code-app",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "dev": "tsx src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "test": "vitest",
    "lint": "eslint src --ext .ts",
    "format": "prettier --write src/**/*.ts"
  },
  "dependencies": {
    "@anthropic-ai/claude-code": "^1.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "@typescript-eslint/eslint-plugin": "^6.0.0",
    "@typescript-eslint/parser": "^6.0.0",
    "eslint": "^8.0.0",
    "prettier": "^3.0.0",
    "tsx": "^4.0.0",
    "typescript": "^5.0.0",
    "vitest": "^1.0.0"
  }
}

Project Setup

Directory Structure

project/
├── .claude/
│   ├── settings.json         # Shared project settings
│   └── settings.local.json   # Local overrides (gitignored)
├── .env                      # Environment variables
├── .env.example              # Example environment file
├── .gitignore                # Include .claude/settings.local.json
├── src/
│   └── index.ts              # Main application
├── hooks/
│   ├── pre-tool-use.sh       # Pre-tool validation
│   └── post-tool-use.sh      # Post-tool formatting
├── mcp-servers/
│   └── custom-tools.js       # Custom MCP server
├── package.json
└── tsconfig.json

.gitignore Configuration

# Claude Code
.claude/settings.local.json
.claude/logs/
.claude/cache/
 
# Environment
.env
.env.local
 
# Dependencies
node_modules/
 
# Build outputs
dist/
build/
 
# IDE
.vscode/
.idea/
 
# OS
.DS_Store
Thumbs.db

Example Project Settings

.claude/settings.json:

{
  "working_directory": ".",
  "permission_mode": "cautious",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./hooks/pre-tool-use.sh",
            "timeout": 10000
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./hooks/post-tool-use.sh",
            "timeout": 15000
          }
        ]
      }
    ]
  }
}

Common Configuration Patterns

Development Configuration

{
  "model": "claude-haiku-4-20250514",
  "permission_mode": "relaxed",
  "max_turns": 10,
  "system_prompt": "You are helping with development. Be concise.",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint:fix",
            "timeout": 20000
          }
        ]
      }
    ]
  }
}

Production Configuration

{
  "model": "claude-sonnet-4-20250514",
  "permission_mode": "strict",
  "max_turns": 3,
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "./security-check.sh",
            "timeout": 30000
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "./audit-log.sh",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

Testing Configuration

{
  "model": "claude-haiku-4-20250514",
  "permission_mode": "cautious",
  "working_directory": "./test-workspace",
  "system_prompt": "You are writing and running tests. Focus on test coverage.",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- --related $CLAUDE_FILE_PATHS",
            "timeout": 60000
          }
        ]
      }
    ]
  }
}

Debugging Configuration

Enable Debug Mode

export CLAUDE_DEBUG=true

Check Current Configuration

# View merged configuration
cat ~/.claude/settings.json
 
# Test hook execution
echo '{"tool_name": "Edit"}' | /path/to/your/hook.sh
 
# Validate JSON syntax
jq '.' ~/.claude/settings.json

Common Issues

  1. Hooks not firing: Check matcher patterns and file permissions
  2. Settings not applying: Verify file locations and JSON syntax
  3. Authentication failing: Check API key in environment or config
  4. MCP tools not available: Restart Claude Desktop after config changes

See Also

Graph View

Backlinks