Claude Code Configuration Files & Directory Structure

Clean Install Directory Structure

What Gets Created on Clean Install

When you install Claude Code and run it for the first time, it creates:

Global Directory: ~/.claude/

~/.claude/
├── .claude.json          # Created automatically - onboarding & auth state
├── settings.json         # NOT created automatically - create manually if needed
├── CLAUDE.md            # Optional - global memory/instructions
├── H.P.002-COMMANDS/            # Optional - custom slash H.P.002-COMMANDS
├── H.P.001-AGENTS/              # Optional - custom subH.P.001-AGENTS
└── bin/                 # Native installer - binary location (sometimes)

Per-Project Directory: .claude/ (in project root)

your-project/
├── .claude/
│   ├── settings.json          # Optional - project-specific H.P.009-CONFIG
│   ├── settings.local.json    # Optional - personal, not committed
│   └── H.P.002-COMMANDS/              # Optional - project H.P.002-COMMANDS
├── CLAUDE.md                   # Optional - project memory/context
└── .mcp.json                   # Optional - MCP server H.P.009-CONFIG

---

Key Configuration Files Explained

1. ~/.claude.json (NOT settings.json)

Location: ~/.claude.json
Created: Automatically on first run
Purpose: Onboarding state, authentication, basic preferences

This is the FIRST file created and is NOT the same as settings.json.

Default/Minimal Content:

{
  "shiftEnterKeyBindingInstalled": false,
  "hasCompletedOnboarding": false,
  "trustedApiKeys": [
    "...last-20-chars-of-your-api-key..."
  ]
}

After Onboarding:

{
  "shiftEnterKeyBindingInstalled": true,
  "hasCompletedOnboarding": true,
  "trustedApiKeys": [
    "abcdef1234567890ABCD"
  ],
  "lastUsedModel": "claude-sonnet-4-5-20250929"
}

Key Points:

• Managed automatically by Claude Code
• Contains authentication state
• NOT the file for advanced H.P.009-CONFIGuration
• Edit with claude H.P.009-CONFIG command, not manually

---

2. ~/.claude/settings.json (Advanced Configuration)

Location: ~/.claude/settings.json
Created: MANUALLY - NOT created on clean install
Purpose: Advanced H.P.009-CONFIGuration, permissions, H.P.005-HOOKS, environment variables

Important: This file does NOT exist after a clean installation. You must create it yourself when you need advanced H.P.009-CONFIGuration.

Minimal/Starter Example:

{
  "model": "claude-sonnet-4-5-20250929",
  "maxTokens": 4096
}

Basic Configuration Example:

{
  "model": "claude-sonnet-4-5-20250929",
  "maxTokens": 4096,
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "NODE_ENV": "development"
  },
  "permissions": {
    "allowedTools": [
      "Read",
      "Write",
      "Bash(git *)",
      "Bash(npm *)"
    ],
    "deny": [
      "Read(.env*)",
      "Write(production.H.P.009-CONFIG.*)",
      "Bash(rm *)",
      "Bash(sudo *)"
    ]
  }
}

Production Configuration Example:

{
  "model": "claude-sonnet-4-5-20250929",
  "maxTokens": 8192,
  "language": "en-US",
  
  "env": {
    "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "NODE_ENV": "development",
    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1"
  },
  
  "permissions": {
    "allowedTools": [
      "Read",
      "Write(src/**)",
      "Write(tests/**)",
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(pytest *)"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Write(.env*)",
      "Write(production.*)",
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(curl *)",
      "WebFetch(*.internal.company.com)"
    ],
    "additionalDirectories": [
      "../shared-utils",
      "../docs"
    ],
    "defaultMode": "default"
  },
  
  "H.P.005-HOOKS": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "H.P.005-HOOKS": [
          {
            "type": "command",
            "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit on main branch\"}' >&2; exit 2; }",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write(*.py)",
        "H.P.005-HOOKS": [
          {
            "type": "command",
            "command": "python -m black $file",
            "description": "Auto-format Python with Black"
          }
        ]
      },
      {
        "matcher": "Write(*.ts)|Write(*.tsx)",
        "H.P.005-HOOKS": [
          {
            "type": "command",
            "command": "npx prettier --write $file",
            "description": "Auto-format TypeScript with Prettier"
          }
        ]
      }
    ]
  },
  
  "attribution": {
    "commit": "🤖 Generated with Claude Code\n\nCo-Authored-By: Claude Sonnet 4.5 <[email protected]>",
    "pr": "Generated with AI assistance"
  },
  
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "git"],
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  }
}

All Available Settings:

{
  // Core Settings
  "model": "claude-sonnet-4-5-20250929",
  "maxTokens": 8192,
  "language": "en-US",
  "temperature": 0.7,
  
  // Environment Variables
  "env": {
    "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5-20250929",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-5-20251101",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
    "API_TIMEOUT_MS": "300000",
    "NODE_ENV": "development",
    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1",
    "DISABLE_TELEMETRY": "0",
    "USE_BUILTIN_RIPGREP": "1"
  },
  
  // Permissions
  "permissions": {
    "allowedTools": ["Read", "Write", "Bash(*)"],
    "deny": ["Read(.env*)", "Bash(rm *)"],
    "additionalDirectories": ["../shared"],
    "defaultMode": "default"  // "default" | "plan" | "auto-accept"
  },
  
  // Hooks (automation)
  "H.P.005-HOOKS": {
    "PreToolUse": [],
    "PostToolUse": [],
    "UserPromptSubmit": []
  },
  
  // Git Attribution
  "attribution": {
    "commit": "Generated with AI",
    "pr": "AI-assisted development"
  },
  
  // Sandbox (if using)
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": [],
    "network": {
      "allowUnixSockets": [],
      "allowLocalBinding": false
    }
  },
  
  // Custom File Autocomplete
  "customFileAutocomplete": {
    "command": "custom-file-search.sh"
  },
  
  // Tool Settings
  "disallowedTools": [],
  "toolSearchEnabled": true,
  
  // Plugin Marketplaces
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "company/claude-plugins"
      }
    }
  }
}

---

3. .claude/settings.json (Project-Specific)

Location: <project>/.claude/settings.json
Created: Manually when needed
Purpose: Project-specific H.P.009-CONFIGuration shared with team
Version Control: ✅ YES - Commit to git

Example:

{
  "permissions": {
    "allowedTools": [
      "Read",
      "Write(src/**)",
      "Bash(npm run test)",
      "Bash(npm run lint)"
    ],
    "deny": [
      "Read(.env*)",
      "Write(package.json)",
      "Bash(npm publish)"
    ]
  },
  
  "H.P.005-HOOKS": {
    "PostToolUse": [
      {
        "matcher": "Write(*.ts)",
        "H.P.005-HOOKS": [
          {
            "type": "command",
            "command": "npm run lint -- --fix $file"
          }
        ]
      }
    ]
  }
}

---

4. .claude/settings.local.json (Personal Overrides)

Location: <project>/.claude/settings.local.json
Created: Manually for personal preferences
Purpose: Personal settings not shared with team
Version Control: ❌ NO - Add to .gitignore

Example:

{
  "model": "claude-opus-4-5-20251101",
  "maxTokens": 8192,
  
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-my-personal-key..."
  }
}

---

5. CLAUDE.md (Memory/Instructions)

Location:

• Global: ~/.claude/CLAUDE.md
• Project: <project>/CLAUDE.md
• Local: <project>/CLAUDE.local.md

Created: Manually
Purpose: Provide context, instructions, and memory to Claude

Example:

# Project Context

## Tech Stack
- Frontend: Next.js 14, TypeScript, Tailwind CSS
- Backend: Node.js, Express, PostgreSQL
- Testing: Jest, Playwright

## Coding Standards
- Use TypeScript strict mode
- Prefer functional components with H.P.005-HOOKS
- Write tests for all new functions
- Follow existing ESLint H.P.009-CONFIGuration

## Architecture
- Components in `src/components/`
- API routes in `pages/api/`
- Utilities in `src/utils/`
- Tests alongside source files (*.test.ts)

## Common Tasks
- Test command: `npm run test`
- Lint command: `npm run lint`
- Build command: `npm run build`

---

6. .mcp.json (MCP Server Configuration)

Location:

• Global: ~/.claude.json (merged)
• Project: <project>/.mcp.json

Created: Via claude mcp add command
Purpose: Configure Model Context Protocol servers

Example:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    },
    "puppeteer": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/puppeteer"]
    }
  }
}

---

Configuration Hierarchy (Precedence)

Settings are applied in this order (highest to lowest priority):

1. Managed Settings (Enterprise - cannot be overridden)

   • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
   • Linux: /etc/claude-code/managed-settings.json
   • Windows: C:\Program Files\ClaudeCode\managed-settings.json

2. Command-line Arguments

   • Example: claude --model claude-opus-4

3. Local Project Settings

   • .claude/settings.local.json

4. Shared Project Settings

   • .claude/settings.json

5. User Settings

   • ~/.claude/settings.json

6. Default Values

   • Built into Claude Code

---

Clean Install: What Files Exist?

Immediately After Install (Before First Run)

# Native installer
~/.local/bin/claude           # Binary (macOS/Linux)
~/.local/share/claude/        # Version info

# npm installer
/usr/local/lib/node_modules/@anthropic-ai/claude-code/
~/.npm-global/bin/claude      # Symlink

# Homebrew
/opt/homebrew/bin/claude      # Binary (Apple Silicon)
/usr/local/bin/claude         # Binary (Intel Mac)

No H.P.009-CONFIGuration files exist yet.

---

After First Run (First Launch)

~/.claude/
├── .claude.json              # ✅ CREATED - onboarding state
└── (nothing else)

That's it. Just one file.

---

After Authentication

~/.claude/
├── .claude.json              # Updated with auth state
└── (still nothing else)

---

If You Create Configuration Files

~/.claude/
├── .claude.json              # Auto-created
├── settings.json             # YOU create this
├── CLAUDE.md                 # YOU create this
├── H.P.002-COMMANDS/                 # YOU create this
│   └── custom-command.md
└── H.P.001-AGENTS/                   # YOU create this
    └── code-reviewer.md

---

How to Create Configuration Files

Creating ~/.claude/settings.json

# Method 1: Create manually
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "model": "claude-sonnet-4-5-20250929",
  "maxTokens": 4096
}
EOF

# Method 2: Ask Claude Code to create it
claude chat
# Then in the chat: "Create a settings.json file in ~/.claude/ with default values"

# Method 3: Copy a template (if you have one)
cp template-settings.json ~/.claude/settings.json

Creating Project .claude/settings.json

# In your project directory
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allowedTools": ["Read", "Write(src/**)"],
    "deny": ["Read(.env*)"]
  }
}
EOF

# Add to git
git add .claude/settings.json
git commit -m "Add Claude Code project H.P.009-CONFIGuration"

Creating .gitignore Entry for Local Settings

# Add to .gitignore
echo ".claude/settings.local.json" >> .gitignore
echo "CLAUDE.local.md" >> .gitignore

---

Checking Your Configuration

View Current Configuration

# Check what exists
ls -la ~/.claude/
ls -la .claude/  # in project directory

# View files
cat ~/.claude.json
cat ~/.claude/settings.json
cat .claude/settings.json

# Check via CLI
claude H.P.009-CONFIG list
claude doctor  # Diagnostics

Test Configuration

# Start Claude Code and check model
claude chat
# Type: /status

# Check permissions
# Type: /allowed-tools

---

Common Configuration Patterns

Pattern 1: API Key via Environment Variable

~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
  }
}

Shell H.P.009-CONFIG (~/.bashrc or ~/.zshrc):

export ANTHROPIC_API_KEY="sk-ant-..."

Pattern 2: Different Models for Different Projects

~/.claude/settings.json (global default):

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

project-a/.claude/settings.json:

{
  "model": "claude-opus-4-5-20251101"
}

project-b/.claude/settings.json:

{
  "model": "claude-haiku-4-5-20251001"
}

Pattern 3: Strict Permissions

{
  "permissions": {
    "allowedTools": [
      "Read(src/**)",
      "Read(tests/**)",
      "Write(src/**)",
      "Write(tests/**)",
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Write(.env*)",
      "Write(package.json)",
      "Bash(npm install*)",
      "Bash(npm publish*)",
      "Bash(rm *)",
      "Bash(sudo *)",
      "WebFetch(*)"
    ]
  }
}

---

Troubleshooting

Issue: "Settings not being applied"

Solution:

# 1. Check file location
ls -la ~/.claude/settings.json

# 2. Validate JSON syntax
cat ~/.claude/settings.json | jq .  # Requires jq

# 3. Restart Claude Code in new terminal
exit  # from current claude session
# Open new terminal
claude chat

# 4. Check effective H.P.009-CONFIGuration
# In claude: /status

Issue: "File doesn't exist on clean install"

This is normal! Create it manually:

mkdir -p ~/.claude
touch ~/.claude/settings.json
# Edit with your preferred editor

Issue: "Project settings not overriding user settings"

Check precedence:

# Verify files exist
ls -la ~/.claude/settings.json
ls -la .claude/settings.json

# Ensure JSON is valid
jq . ~/.claude/settings.json
jq . .claude/settings.json

# Project settings (.claude/settings.json) should override user settings

---

Best Practices

1. Start minimal - Don't create settings.json until you need it
2. Use environment variables - Keep API keys out of JSON files
3. Version control project settings - Commit .claude/settings.json
4. Don't commit local settings - Add .claude/settings.local.json to .gitignore
5. Document in CLAUDE.md - Explain project-specific requirements
6. Use H.P.005-HOOKS for automation - Auto-format, lint, test
7. Test permissions carefully - Start restrictive, relax as needed
8. Keep backups - cp ~/.claude/settings.json ~/.claude/settings.json.bak

---

Quick Reference

File	Auto-Created?	Location	Purpose	Commit to Git?
.claude.json	✅ Yes	~/.claude/	Auth & onboarding state	❌ No
settings.json	❌ No	~/.claude/	User H.P.009-CONFIG	❌ No
settings.json	❌ No	.claude/	Project H.P.009-CONFIG	✅ Yes
settings.local.json	❌ No	.claude/	Personal overrides	❌ No
CLAUDE.md	❌ No	~/ or project	Memory/instructions	✅ Yes (project)
.mcp.json	❌ No	Project	MCP servers	✅ Maybe

---

Summary

Key Takeaways:

1. Clean install creates ONLY ~/.claude.json - NOT settings.json
2. You must create settings.json manually when you need advanced H.P.009-CONFIGuration
3. Configuration is hierarchical - project overrides user overrides defaults
4. Start simple - Add H.P.009-CONFIGuration as you need it
5. Use version control - Share project settings, keep personal settings private

First Steps After Install:

# 1. Install
curl -fsSL https://claude.ai/install.sh | bash

# 2. Authenticate
claude auth login

# 3. Check what was created
ls -la ~/.claude/

# 4. Create settings.json only when needed
# (Don't create it unless you have specific requirements)

# 5. Start using Claude Code
cd your-project
claude chat