Claude Code Configuration

Work with Claude Code configuration at any level - global (~/.claude/) or project (.claude/).

First: Determine Context

Before making changes, identify where you're working and what already exists:

# Where are we?
pwd

# In a project repo or in ~/.claude itself?
[[ "$(pwd)" == "$HOME/.claude"* ]] && echo "GLOBAL" || echo "PROJECT"

# What config exists at each level?
ls -la ~/.claude/settings.json ~/.claude.json 2>/dev/null
ls -la .claude/settings.json .mcp.json 2>/dev/null

Context determines approach:

Working in Project Context

When configuring a project's .claude/ directory, always follow this workflow:

1. Audit Global Config First

Before adding anything to project config, examine what's already defined globally:

# Check global settings
cat ~/.claude/settings.json 2>/dev/null | jq .

# Check global MCP servers
cat ~/.claude.json 2>/dev/null | jq .mcpServers

# List global agents, commands, skills
ls ~/.claude/agents/ ~/.claude/commands/ ~/.claude/skills/ 2>/dev/null

2. Apply the Reuse Principle

Only add to project config what is:

• •Unique to this project (project-specific MCP servers, custom workflows)
• •Overriding global behavior intentionally (stricter permissions, different model)
• •Sharable with the team via version control

Do NOT duplicate:

• •Permissions already in global config
• •MCP servers you use across all projects
• •Personal agents/skills that aren't project-specific

3. Explain Your Reasoning

When making recommendations, always explain WHY:

**Recommendation:** Add this permission to `.claude/settings.json`

**Reasoning:** This permission is project-specific because:
- It references paths unique to this project (`./src/api/**`)
- The global config doesn't cover this use case
- Team members will need this when they clone the repo

**Not adding to global because:** This pattern only makes sense for this project's structure.

Placement Decision Guide

Use this to decide where configuration belongs:

Configuration Hierarchy

Settings merge from general to specific (later overrides earlier):

1. •Global: ~/.claude/settings.json - applies to all projects
2. •Project: .claude/settings.json - project-specific, git-committed
3. •Local: .claude/settings.local.json - per-machine, gitignored

For MCP servers:

• •Global: ~/.claude.json (mcpServers key)
• •Project: .mcp.json (mcpServers key)

For instructions:

• •Global: ~/.claude/CLAUDE.md
• •Project: CLAUDE.md or .claude/CLAUDE.md

Configuration Inventory

Scan projects for Claude Code configuration status and identify overlap:

bun ~/.claude/skills/dotclaude-config/scripts/inventory.ts          # scan ~/code/
bun ~/.claude/skills/dotclaude-config/scripts/inventory.ts ~/work   # custom path

Reports: configured vs unconfigured projects, skill counts, package managers, and flags project skills that shadow global skills (candidates for removal or promotion to global).

Using Built-in Subagents

claude-code-guide

Query official Claude Code documentation:

Task(subagent_type="claude-code-guide", prompt="How do hooks work in settings.json?")

When to use: Latest features, undocumented behavior, syntax verification.

Explore

Examine actual configuration across levels:

Task(subagent_type="Explore", prompt="Compare global and project permissions")
Task(subagent_type="Explore", prompt="What MCP servers are configured at each level?")

When to use: Understanding current state, finding conflicts, debugging.

Quick Reference

Permissions

"permissions": {
  "allow": ["Bash(git status)", "Read(./src/**)"],
  "deny": ["Read(.env)", "Read(**/*.key)"],
  "ask": ["Bash(git push:*)"]
}

Hooks

"hooks": {
  "PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "..."}]}]
}

Model

"model": "opus"  // or "sonnet", "haiku"

CLAUDE.md Configuration

For authoring and organizing CLAUDE.md files — placement, @path imports, rules files, size management — see references/claude-md-patterns.md.

Key rules:

• •Keep CLAUDE.md concise (<500 lines); use @path imports for detail
• •Use .claude/rules/*.md for modular, auto-loaded instructions
• •Put personal preferences in ~/.claude/CLAUDE.md, project context in project CLAUDE.md

Working in ~/.claude Itself

When the current directory IS ~/.claude (e.g., this config is a git repo):

• •Everything is global — changes affect all Claude Code sessions
• •Skills, agents, commands created here are available everywhere
• •settings.json here is the global config, not a project override
• •CLAUDE.md at the root is your personal instructions for all projects
• •Treat it as a public repo if published — never commit secrets

Detailed Documentation

• •settings.json schema: See references/settings-json.md
• •MCP configuration: See references/mcp-config.md
• •Extensibility (agents/commands/skills): See references/extensibility.md
• •CLAUDE.md patterns: See references/claude-md-patterns.md

Example: Project Config Audit

When asked to configure a project, produce an audit like this:

## Configuration Audit

### Global Config (already have)
- **Permissions**: deny secrets/keys, allow git commands
- **MCP**: perplexity-mcp (personal)
- **Hooks**: PostToolUse formatter, Stop session-title
- **Model**: opus

### Project Needs
- Custom permission for `./packages/**` paths
- MCP server for project's Supabase instance
- Agent for project's deployment workflow

### Recommendations

1. **Add to `.claude/settings.json`:**
   ```json
   {"permissions": {"allow": ["Read(./packages/**)"]}}

Reasoning: Project-specific path not in global config

1. •

   Add to .mcp.json:

   json

   {"mcpServers": {"supabase": {...}}}
   

   Reasoning: Project database, needs team access via git

2. •

   Skip adding:

   • •General git permissions (already global)
   • •Perplexity MCP (personal, not project-specific)
   • •Formatter hooks (already in global PostToolUse)

## Common Tasks

### Add a project-specific permission

First check global: `cat ~/.claude/settings.json | jq .permissions`

If not covered, add to `.claude/settings.json`:
```json
"permissions": {"allow": ["Bash(npm run build:*)"]}

Add a project MCP server

Add to .mcp.json (not ~/.claude.json) so team gets it:

{"mcpServers": {"project-db": {"command": "...", "env": {"DB_URL": "${PROJECT_DB_URL}"}}}}

Create a project-specific agent

Create .claude/agents/deploy.md for project workflows. Keep personal agents in ~/.claude/agents/.

Override global settings

Project settings merge with (and can override) global:

// .claude/settings.json - stricter for this project
{"permissions": {"deny": ["Write(./contracts/**)"]}}