Where Claude Code Stores Configuration Files

Claude Code stores configuration files in predictable locations across all platforms. Understanding where these files live helps you backup settings, migrate between machines, troubleshoot issues, and customize your development environment.

Main Configuration Directory

All Claude Code configuration lives under a single directory:

All Platforms:

~/.claude/

Platform-specific paths:

Complete Directory Structure

Here's the full layout of Claude Code's configuration directory:

~/.claude/
├── settings.json           # Global user settings
├── settings.local.json     # Local user settings (not synced)
├── CLAUDE.md               # Global instructions for all projects
├── .credentials.json       # API credentials (Linux/Windows only)
├── statsig/                # Analytics cache
│   └── ...
├── commands/               # Global custom slash commands
│   ├── review.md
│   ├── test.md
│   └── ...
└── projects/               # Session history per project
    ├── -Users-sean-myproject/
    │   ├── session-2025-01-15.jsonl
    │   └── session-2025-01-16.jsonl
    └── -home-user-another-project/
        └── ...

# Project-level files (in your project root)
./
├── CLAUDE.md               # Project-specific instructions
├── CLAUDE.local.md         # Personal project instructions (gitignored)
├── .mcp.json               # Project MCP server configuration
└── .claude/
    ├── settings.json       # Project settings (shared)
    ├── settings.local.json # Project settings (personal)
    └── commands/           # Project-specific slash commands
        └── deploy.md

# User-level MCP configuration (outside .claude directory)
~/.claude.json              # User MCP server configuration

Configuration Files Explained

Settings Files

Claude Code uses a hierarchy of settings files, loaded from least specific to most specific:

Global user settings:

~/.claude/settings.json

Controls default behavior for all projects. Example:

{
  "permissions": {
    "allow": ["Bash(npm run:*)", "Read", "Write"],
    "deny": ["Bash(rm -rf:*)"]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

Local user settings (not synced):

~/.claude/settings.local.json

Personal overrides that shouldn't sync across machines. Add machine-specific paths or credentials here.

Project settings (shared):

.claude/settings.json

Commit this to version control for team-shared configuration.

Project settings (personal):

.claude/settings.local.json

Add to .gitignore for personal project preferences.

Settings Precedence

Settings are merged in this order (later entries override earlier):

1. Defaults - Built-in Claude Code defaults
2. User settings - ~/.claude/settings.json
3. Shared project settings - .claude/settings.json
4. Local project settings - .claude/settings.local.json
5. CLI flags - Command-line arguments
6. Enterprise policies - Organization-level overrides (if applicable)

CLAUDE.md Files

Project instructions that Claude reads at the start of every session:

Global instructions:

~/.claude/CLAUDE.md

Applies to all projects. Good for personal coding style preferences.

Project instructions:

./CLAUDE.md

Project-specific standards. Commit to version control for team sharing.

Local project instructions:

./CLAUDE.local.md

Personal project overrides. Add to .gitignore.

See How to Configure CLAUDE.md for detailed guidance.

MCP Server Configuration

Model Context Protocol servers extend Claude Code's capabilities:

User-scoped MCP servers:

~/.claude.json

Note: This file is at ~/.claude.json, not inside the ~/.claude/ directory.

Example:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    }
  }
}

Project-scoped MCP servers:

./.mcp.json

Commit this for project-specific MCP servers your team needs.

See How to Set Up MCP Servers for configuration details.

Credentials

macOS: Credentials are stored securely in the system Keychain. Access them via Keychain Access.app under "Claude Code" or "Anthropic".

Linux and Windows:

~/.claude/.credentials.json

This file contains your authentication tokens. Never share or commit this file.

Session History

Claude Code stores conversation history for each project:

~/.claude/projects/{encoded-project-path}/

The project path is URL-encoded (slashes become dashes). For example:

• /Users/sean/myproject becomes -Users-sean-myproject

Each session creates a .jsonl file:

~/.claude/projects/-Users-sean-myproject/
├── session-2025-01-15-09-30-00.jsonl
├── session-2025-01-15-14-22-00.jsonl
└── session-2025-01-16-10-00-00.jsonl

Custom Commands

Create reusable slash commands in markdown files:

Global commands (all projects):

~/.claude/commands/
├── review.md
├── test.md
└── commit.md

Project commands:

.claude/commands/
├── deploy.md
└── setup.md

Invoke with /commandname in Claude Code.

Cache Directory

Analytics and performance cache:

~/.claude/statsig/

Safe to delete if you need to clear cache. Claude Code will recreate it.

Environment Variables

Claude Code respects these environment variables:

Set these in your shell profile (~/.zshrc, ~/.bashrc) or system environment.

Platform-Specific Details

macOS

Default paths:

# Configuration
~/.claude/

# Credentials (Keychain)
# Access via: Keychain Access.app > login > "Claude Code"

# MCP servers
~/.claude.json

# Check actual location
echo $HOME/.claude

Windows (Native)

Default paths:

# Configuration
%USERPROFILE%\.claude\

# Credentials
%USERPROFILE%\.claude\.credentials.json

# MCP servers
%USERPROFILE%\.claude.json

# Check actual location
echo $env:USERPROFILE\.claude

Windows (WSL)

When using Claude Code in WSL, configuration follows Linux conventions:

# Configuration
~/.claude/

# This is separate from Windows native installation
# WSL path: /home/username/.claude/
# Windows path: C:\Users\username\.claude\

Linux

Default paths:

# Configuration
~/.claude/

# Credentials
~/.claude/.credentials.json

# MCP servers
~/.claude.json

# Create directory if missing
mkdir -p ~/.claude

Backup and Migration

Backup Your Configuration

Create a complete backup:

# macOS/Linux
tar -czvf claude-backup.tar.gz \
  ~/.claude/settings.json \
  ~/.claude/settings.local.json \
  ~/.claude/CLAUDE.md \
  ~/.claude/commands/ \
  ~/.claude.json

# Windows PowerShell
Compress-Archive -Path "$env:USERPROFILE\.claude\settings.json", `
  "$env:USERPROFILE\.claude\CLAUDE.md", `
  "$env:USERPROFILE\.claude\commands", `
  "$env:USERPROFILE\.claude.json" `
  -DestinationPath claude-backup.zip

Do not backup:

• .credentials.json - Re-authenticate on new machines
• statsig/ - Cache, will regenerate
• projects/ - Session history, usually not needed

Migrate to a New Machine

1. Copy configuration files:

   # On new machine
   mkdir -p ~/.claude/commands
   
   # Copy from backup
   tar -xzvf claude-backup.tar.gz -C ~/
   

   Copy

2. Re-authenticate:

   claude
   # Follow the browser authentication flow
   

   Copy

3. Verify configuration:

   claude doctor
   

   Copy

Sync Across Machines

For ongoing synchronization, symlink to a synced folder:

# Example using Dropbox
mkdir -p ~/Dropbox/claude-config

# Move and symlink settings
mv ~/.claude/settings.json ~/Dropbox/claude-config/
ln -s ~/Dropbox/claude-config/settings.json ~/.claude/settings.json

# Move and symlink CLAUDE.md
mv ~/.claude/CLAUDE.md ~/Dropbox/claude-config/
ln -s ~/Dropbox/claude-config/CLAUDE.md ~/.claude/CLAUDE.md

Troubleshooting

Configuration Not Loading

1. Verify the file exists and has correct permissions:

   ls -la ~/.claude/
   

   Copy

2. Check file syntax (valid JSON for settings):

   cat ~/.claude/settings.json | python -m json.tool
   

   Copy

3. Run diagnostics:

   claude doctor
   

   Copy

Permission Errors

# Fix permissions on macOS/Linux
chmod 700 ~/.claude
chmod 600 ~/.claude/settings.json
chmod 600 ~/.claude/.credentials.json

Credentials Not Found

If Claude Code cannot find your credentials:

1. Check if credentials file exists (Linux/Windows):

   ls -la ~/.claude/.credentials.json
   

   Copy

2. On macOS, verify Keychain entry:

   • Open Keychain Access
   • Search for "Claude" or "Anthropic"
   • Ensure the entry exists and is not locked

3. Re-authenticate:

   claude logout
   claude
   

   Copy

Reset Configuration

To start fresh:

# Backup first
cp -r ~/.claude ~/.claude.backup

# Remove configuration (preserves credentials on macOS Keychain)
rm -rf ~/.claude/settings.json
rm -rf ~/.claude/settings.local.json
rm -rf ~/.claude/statsig

# Or complete reset (requires re-authentication)
rm -rf ~/.claude

Next Steps

• Install Claude Code CLI if you haven't already
• Configure CLAUDE.md for your projects
• Set up MCP servers to extend capabilities
• Manage permissions for security

Need help configuring Claude Code for your team? Inventive HQ helps organizations standardize AI coding tool configurations. Contact us for enterprise setup assistance.