Claude Code Configuration

Work with Claude Code configuration at any level - global (~/.claude/) or project (.claude/). <!-- portability: allow -->

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 the global config dir itself?
[[ "$(pwd)" == "$HOME/.claude"* ]] && echo "GLOBAL" || echo "PROJECT"  # portability: allow

# What config exists at each level?
ls -la ~/.claude/settings.json ~/.claude.json 2>/dev/null  # portability: allow
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 .  # portability: allow

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

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

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 <!-- portability: allow -->
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) <!-- portability: allow -->
• Project: .mcp.json (mcpServers key)

For instructions:

• Global: ~/.claude/CLAUDE.md <!-- portability: allow -->
• Project: CLAUDE.md or .claude/CLAUDE.md

Configuration Inventory

Scan projects for Claude Code configuration status and identify overlap. Paths below are relative to this skill's base directory:

bun scripts/inventory.ts          # scan ~/code/
bun 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](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 <!-- portability: allow -->

Working in ~/.claude Itself <!-- portability: allow -->

When the current directory IS ~/.claude: <!-- portability: allow -->

• Everything is global — changes affect all Claude Code sessions
• Treat it as a public repo — never commit secrets

Two-Clone Architecture

~/.claude is an independent clone that deploys from origin/main. Development happens in ~/code/dotclaude on feature branches. Never commit directly to ~/.claude — it's the deploy target. <!-- portability: allow -->

# Verify: the global config dir should be a standalone clone, NOT a worktree
[ -d ~/.claude/.git ] && echo "STANDALONE (correct)" || echo "WORKTREE — see development-workflow.md to migrate"  # portability: allow

• ~/code/dotclaude — feature branches, PRs, all development
• ~/.claude — always on main, updated by SessionStart hook (scripts/deploy.sh) <!-- portability: allow -->
• Runtime config changes stay in ~/.claude/settings.json — it is gitignored; settings.example.json is the tracked shape and changes by PR <!-- portability: allow -->

See [references/development-workflow.md](references/development-workflow.md) for setup, symlink workflow, and migration from worktree.

Detailed Documentation

• settings.json schema: See [references/settings-json.md](references/settings-json.md)
• MCP configuration: See [references/mcp-config.md](references/mcp-config.md)
• Extensibility (agents/commands/skills): See [references/extensibility.md](references/extensibility.md)
• CLAUDE.md patterns: See [references/claude-md-patterns.md](references/claude-md-patterns.md)
• Hooks reference: See [references/hooks-reference.md](references/hooks-reference.md)
• Hook patterns: See [references/hook-patterns.md](references/hook-patterns.md)
• Permission templates: See [references/permission-templates.md](references/permission-templates.md)
• Project config checklist: See [references/project-config-checklist.md](references/project-config-checklist.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*

2. **Add to `.mcp.json`:**
   ```json
   {"mcpServers": {"supabase": {...}}}
   ```
   *Reasoning: Project database, needs team access via git*

3. **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 <!-- portability: allow -->

If not covered, add to .claude/settings.json:

"permissions": {"allow": ["Bash(npm run build:*)"]}

Add a project MCP server

Add to .mcp.json (not ~/.claude.json) so team gets it: <!-- portability: allow -->

{"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/. <!-- portability: allow -->

Override global settings

Project settings merge with (and can override) global:

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