claude-config

Claude Code Configuration Expert

I'm your comprehensive guide to Claude Code configuration. I understand the complete hierarchy and precedence system, from enterprise policies down to local project settings.

Quick Help - Most Common Issues

"My plugin isn't working"

1. Check enabled in ~/.claude/settings.json under enabledPlugins
2. Verify symlink exists: ls -la ~/.claude/plugins/
3. Validate plugin.json: claude plugin validate <path>
4. Restart Claude Code after changes

"Settings not applying"

Precedence order (highest to lowest):

1. Enterprise managed policies
2. Command line arguments
3. .claude/settings.local.json (project, personal)
4. .claude/settings.json (project, shared)
5. ~/.claude/settings.json (user, global)

"CLAUDE.md not loading"

Loading order (highest precedence first):

1. Enterprise: /Library/Application Support/ClaudeCode/CLAUDE.md (macOS)
2. Project: ./CLAUDE.md or ./.claude/CLAUDE.md
3. User: ~/.claude/CLAUDE.md

Files load automatically at launch. Use /memory to verify loaded content.

"MCP not showing up" ⚠️ CRITICAL

The Real Config File:

• ❌ ~/.claude/mcp.json exists but IS IGNORED by Claude Code
• ✅ ~/.claude.json (in home directory) is the actual config Claude Code reads
• MCPs are stored per-project at projects['/path/to/project']['mcpServers']

How to properly add MCPs:

# Use the CLI - it knows the correct file
cd /path/to/project
claude mcp add --transport stdio my-mcp --env KEY=value -- /path/to/binary --args

# Verify it was added
claude mcp list

# Test without restarting session (headless)
claude -p "what MCP tools are available?"

Configuration Types - When to Use Each

CLAUDE.md - Persistent Instructions

• Purpose: Team/personal coding standards that persist across sessions
• Location: Project root or .claude/ folder
• Use for: Coding conventions, build commands, architecture patterns
• NOT for: Agent definitions or interactive commands

agent.md - Specialized Assistants

• Purpose: Define subagents with specific expertise
• Location: .claude/agents/ (project) or ~/.claude/agents/ (user)
• Format: Markdown with YAML frontmatter
• Use for: Domain-specific assistants (backend-dev, qa-engineer, etc.)

Skills - Model-Invoked Capabilities

• Purpose: Extend Claude's autonomous capabilities
• Location: .claude/skills/skill-name/SKILL.md
• Claude decides when to use based on context
• Use for: Reusable workflows Claude should recognize

Slash Commands - User-Invoked Actions

• Purpose: Quick access to common prompts
• Location: .claude/commands/ or ~/.claude/commands/
• You explicitly type /command to trigger
• Use for: Frequent operations like /commit or /review

Hooks - Event Automation

• Purpose: Intercept and modify Claude's behavior
• Configure in: settings.json under "hooks"
• Use for: Validation, formatting, logging, blocking dangerous operations

The .local Convention

Files ending in .local are automatically gitignored and used for personal preferences:

• .claude/settings.local.json - Personal project settings
• Never use CLAUDE.local.md (deprecated)
• Perfect for: API keys, personal tool preferences, experiments

Directory Structure Reference

~/                             # Home directory
└── .claude.json               # ⚠️ THE ACTUAL CONFIG FILE (MCP + settings + projects)

~/.claude/                      # User-level (global)
├── settings.json               # Global settings (deprecated location)
├── mcp.json                   # IGNORED - do not use!
├── CLAUDE.md                  # Global instructions
├── agents/                    # Global subagents
├── skills/                    # Global skills
├── commands/                  # Global slash commands
└── plugins/                   # Installed plugins (usually symlinks)

./.claude/                     # Project-level (shared via git)
├── settings.json              # Team settings
├── settings.local.json        # Personal settings (gitignored)
├── CLAUDE.md                  # Project instructions
├── agents/                    # Project subagents
├── skills/                    # Project skills
└── commands/                  # Project slash commands

⚠️ Critical: All MCP configurations are stored in ~/.claude.json (in home directory) under the projects key, organized by project directory path.

MCP Server Setup

⚠️ IMPORTANT: Where MCPs Are Actually Stored

Claude Code stores MCP configurations in ~/.claude.json in your home directory (NOT ~/.claude/mcp.json):

{
  "projects": {
    "/path/to/project": {
      "mcpServers": {
        "my-mcp": {
          "type": "stdio",
          "command": "/path/to/binary",
          "args": ["--stdio"],
          "env": {"KEY": "value"}
        }
      }
    }
  }
}

Per-Project Configuration:

• Each project directory gets its own mcpServers config
• Use claude mcp add from within project directory
• MCPs are context-aware based on working directory

Basic Configuration (CLI Method - RECOMMENDED)

# Always use CLI to add MCPs (it handles the complex .claude.json format)
claude mcp add --transport stdio memory \
  --env STORAGE_PATH=/tmp/memory \
  -- npx @anthropic/memory-mcp-server

# For MCPs with multiple env vars
claude mcp add --transport stdio looker-toolbox \
  --env LOOKER_BASE_URL=https://your.looker.com \
  --env LOOKER_CLIENT_ID=your_id \
  --env LOOKER_CLIENT_SECRET=your_secret \
  -- /path/to/looker-toolbox --stdio --prebuilt looker

Transport Types

• stdio: Local processes (most common)
• http: Remote APIs
• sse: Server-sent events (deprecated)

Troubleshooting MCP

Step 1: Verify MCP is registered

claude mcp list  # Shows connected MCPs
claude mcp get <name>  # Show specific MCP config

Step 2: Test MCP without restarting 🚀

# Test in headless mode to avoid losing context
claude chat "list all available MCP tools"
claude chat "call mcp__<server-name>__<tool-name>"

# Test specific MCP server directly
LOOKER_BASE_URL=... /path/to/binary --stdio <<< '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

Step 3: Common issues

1. ❌ Wrong file: Don't edit ~/.claude/mcp.json - it's ignored
2. ✅ Use CLI: claude mcp add writes to correct location (.claude.json)
3. ✅ Check paths: Commands must be executable and exist
4. ✅ Environment vars: Must be set in MCP config's env object
5. ⚠️ Session restart: New MCPs only load in new sessions (use headless testing!)

Plugin & Marketplace System

Installing Plugins

# Add marketplace
claude plugin marketplace add owner/repo

# Install plugin
claude plugin install plugin-name@marketplace

# Create symlink if missing
ln -s /path/to/plugin ~/.claude/plugins/plugin@marketplace

Plugin Structure

plugin-root/
├── .claude-plugin/
│   ├── plugin.json           # Required manifest (metadata only)
│   └── marketplace.json      # Required for marketplaces
├── commands/                 # Slash commands (at root) - auto-discovered
├── skills/                   # Skills (at root) - auto-discovered
├── agents/                   # Subagents (at root) - auto-discovered
└── hooks/
    └── hooks.json            # Hook configuration file

CRITICAL: Plugin.json Schema

The plugin.json file should contain metadata only. Commands, skills, agents, and hooks are auto-discovered from their directories:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]"
  },
  "repository": "https://github.com/...",
  "license": "MIT",
  "keywords": ["tag1", "tag2"]
}

What NOT to include in plugin.json:

• ❌ commands array - Commands auto-discovered from commands/*.md
• ❌ skills array - Skills auto-discovered from skills/*/SKILL.md
• ❌ agents array - Agents auto-discovered from agents/*.md
• ❌ hooks object - Hooks defined in hooks/hooks.json file instead
• ❌ displayName field - Not part of schema
• ❌ requirements object - Not part of schema

Author field must be an object:

"author": {
  "name": "Your Name",
  "email": "[email protected]",  // optional
  "url": "https://..."          // optional
}

How Auto-Discovery Works:

• Commands: All *.md files in commands/ become slash commands
• Skills: Each SKILL.md file in skills/skill-name/ becomes a skill
• Agents: All *.md files in agents/ become agents
• Hooks: Configuration read from hooks/hooks.json

Marketplace Debugging

• One marketplace per plugin source
• Remove duplicates: claude plugin marketplace remove <name>
• List all: claude plugin marketplace list
• Validate: claude plugin validate <path>

Advanced Configurations

Hook Example - Block Dangerous Commands

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./validate-bash.sh"
      }]
    }]
  }
}

Multi-Environment MCP

{
  "mcpServers": {
    "db": {
      "type": "stdio",
      "command": "psql-mcp",
      "env": {
        "DATABASE_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
      }
    }
  }
}

Debugging Commands

Quick Config Checks

# View actual config file (where MCPs really live)
cat ~/.claude.json | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('projects', {}).get('$(pwd)', {}), indent=2))"

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

# Check loaded memories
/memory  # In Claude Code

# List plugins
ls -la ~/.claude/plugins/

# Validate configurations
claude plugin validate .
claude mcp list
claude mcp get <server-name>

🚀 Headless Testing (Test Without Losing Context)

# Test if new MCPs are working without restarting current session
claude -p "what MCP servers are available?"
claude -p "list all tools from looker-toolbox"
claude -p "use the claude-config skill"

# Test MCP directly
LOOKER_BASE_URL=... /path/to/mcp-binary --stdio <<< '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Test skills/commands in fresh session
claude -p "/commit"  # Test slash command
claude -p "invoke the graphite-workflow skill"  # Test skill

Cleanup

# Clean debug logs
find ~/.claude/debug -mtime +7 -delete

Best Practices

For Teams

1. Share .claude/settings.json in git
2. Document CLAUDE.md conventions
3. Create project-specific agents
4. Use hooks for code standards

For Individuals

1. Keep personal prefs in settings.local.json
2. Global shortcuts in ~/.claude/commands/
3. Experiment with skills before sharing
4. Regular cleanup of debug files

Common Pitfalls to Avoid

MCP Configuration

❌ Editing ~/.claude/mcp.json (file is ignored!) ❌ Manually editing .claude.json (use CLI instead) ❌ Forgetting environment variables in MCP config ✅ Use claude mcp add CLI for all MCP operations ✅ Use claude mcp list to verify MCP is connected ✅ Test MCPs headlessly: claude -p "list MCP tools" ✅ All MCPs live in .claude.json under projects['/path']['mcpServers']

Plugin Management

❌ Multiple marketplaces pointing to same directory ❌ Manually editing enabledPlugins without installing ❌ Putting marketplace.json at plugin root (must be in .claude-plugin/) ❌ Putting commands/skills/agents/hooks in .claude-plugin/ (must be at plugin root) ✅ One marketplace per source ✅ Use CLI for plugin management ✅ Keep plugin.json AND marketplace.json in .claude-plugin/ ✅ Keep commands/skills/agents/hooks at plugin root level

Configuration Files

❌ Using CLAUDE.local.md (deprecated) ❌ Editing .claude.json manually (use CLI) ✅ Use settings.local.json for local config ✅ Use claude mcp add for MCP config ✅ Test changes headlessly to avoid restarts

---

Need deeper information? Ask me about specific topics like "MCP scope hierarchy", "hook event types", or "CLAUDE.md import syntax".