Claude Code

Claude Code Configuration Reference

Complete .claude Directory Structure

.claude/
├── CLAUDE.md                    # Project instructions (auto-loaded, shared via git)
├── settings.json                # Project settings (shared via git)
├── settings.local.json          # Local project settings (auto-gitignored)
│
├── commands/                    # Custom slash commands
│   ├── review.md                # /review
│   ├── optimize.md              # /optimize
│   ├── frontend/                # Namespaced: shows as "(project:frontend)"
│   │   └── component.md         # /component
│   └── backend/                 # Namespaced: shows as "(project:backend)"
│       └── test.md              # /test
│
├── skills/                      # Agent Skills (auto-discovered)
│   └── pdf-processor/
│       ├── SKILL.md             # Required: skill definition
│       ├── helper.py            # Optional: supporting scripts
│       └── templates/           # Optional: resources
│
├── agents/                      # Custom subagents
│   ├── code-reviewer.md         # Specialized code review agent
│   ├── tester.md                # Testing specialist
│   └── security-auditor.md      # Security-focused agent
│
└── rules/                       # Modular instructions (auto-loaded)
    ├── code-style.md
    ├── testing.md
    └── frontend/                # Subdirectories supported
        └── components.md

# Project root
CLAUDE.md                        # Alternative location for project memory
CLAUDE.local.md                  # Personal project memory (auto-gitignored)
.mcp.json                        # Project MCP servers (shared via git)

# User-level (all projects)
~/.claude/
├── CLAUDE.md                    # Personal memory (all projects)
├── settings.json                # User settings
├── commands/                    # Personal commands - shows as "(user)"
├── skills/                      # Personal skills
├── agents/                      # Personal subagents
└── rules/                       # Personal rules

~/.claude.json                   # User config (MCP servers, theme, OAuth)

Quick Feature Comparison

Memory & Context

TLDR: Claude Code uses Markdown files for persistent memory. CLAUDE.md files are auto-loaded at startup. There is NO memory.json file.

Memory Hierarchy (highest to lowest precedence)

1. Enterprise policy: /Library/Application Support/ClaudeCode/CLAUDE.md (macOS)
2. Project memory: ./CLAUDE.md or ./.claude/CLAUDE.md
3. Project rules: ./.claude/rules/*.md
4. User memory: ~/.claude/CLAUDE.md
5. Project local: ./CLAUDE.local.md (auto-gitignored)

Nested CLAUDE.md Files

Claude reads CLAUDE.md files in subdirectories on-demand when accessing that directory:

project/
├── CLAUDE.md                 # Auto-loaded at startup
├── src/
│   └── api/
│       └── CLAUDE.md         # Loaded when Claude accesses src/api/
└── tests/
    └── CLAUDE.md             # Loaded when Claude accesses tests/

• Root-level: Auto-loaded at session start
• Nested: Loaded when Claude reads files in that directory
• Parent lookup: Claude searches up the directory tree, so parent instructions apply to subdirectories

CLAUDE.md Format

# Project Name

## Overview
Brief description of the project.

## Coding Conventions
- Use ESLint and Prettier
- Follow TypeScript best practices

## File Structure
- `src/components/` - React components
- `src/utils/` - Utility functions

## Import Instructions
@path/to/other-instructions.md

Key Commands

• /memory - Edit CLAUDE.md files directly
• /compact [instructions] - Compress context, optionally focus on specific info
• /context - Visualize current context usage

Session Storage

• Conversation history: In-memory only (current session)
• Checkpoints: Auto-created before edits, persist 30 days
• TODOs: Session-based via /todos
• Rewind: Esc + Esc or /rewind to restore previous state

Skills

TLDR: Modular capabilities that Claude automatically discovers and uses based on context. Each skill is a folder with a SKILL.md file. Skills are model-invoked (not user-invoked like slash commands).

Locations

SKILL.md Format

---
name: pdf-processor
description: Extract text from PDFs, fill forms, merge documents. Use when working with PDF files.
allowed-tools: Read, Grep, Bash
---

# PDF Processor

## Instructions
Step-by-step guidance for Claude.

## Examples
Concrete examples of using this skill.

Field Reference

Note: Skills are different from allowedTools in settings.json. Skills package expertise; settings control global tool permissions.

Subagents

TLDR: Specialized AI assistants with isolated context. Claude auto-delegates tasks or you can request specific agents. Define as Markdown files in .claude/agents/ or ~/.claude/agents/.

Agent File Format

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. Focus on:
- Code quality and best practices
- Security vulnerabilities
- Performance issues

Field Reference

Built-in Subagents

• General-purpose: Complex multi-step tasks (Sonnet, all tools)
• Plan: Read-only analysis and planning (Read, Glob, Grep, Bash)
• Explore: Fast codebase searching (Haiku, read-only)

Management

• /agents - Interactive UI to create, edit, delete subagents
• View available tools and configure permissions

Slash Commands

TLDR: Quick shortcuts invoked with /. Custom commands are Markdown files.

Built-in Commands

Custom Command Format

Location: .claude/commands/ (project) or ~/.claude/commands/ (user)

---
description: Create a git commit with AI-generated message
allowed-tools: Bash(git add:*), Bash(git commit:*)
argument-hint: [message]
---

Create a git commit with message: $ARGUMENTS

## Context
- Current status: !`git status`
- Current diff: !`git diff HEAD`

Arguments

• $ARGUMENTS - All arguments as single string
• $1, $2, etc. - Positional arguments
• !`command` - Execute bash before prompt runs
• @path/to/file - Include file contents

Hooks

TLDR: Event-driven automation configured in settings.json (not separate files).

Configuration Location

Hooks go in settings.json under the "hooks" key:

• ~/.claude/settings.json - User hooks
• .claude/settings.json - Project hooks
• .claude/settings.local.json - Local hooks

Supported Events

Schema

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --fix",
            "timeout": 60
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 validate-command.py"
          }
        ]
      }
    ]
  }
}

Matcher Patterns

• "Write" - Exact match
• "Edit|Write" - Regex OR
• "mcp__github__.*" - MCP tool pattern
• "*" - All tools

Hook Output

• Exit 0: Success (stdout shown in verbose mode)
• Exit 2: Block the operation (stderr shown as error)
• Other: Non-blocking error

Management

• /hooks - Interactive UI to manage hooks

Rules

TLDR: Modular project instructions in .claude/rules/. Auto-loaded at startup. Support path targeting.

Directory Structure

.claude/rules/
├── code-style.md
├── testing.md
├── security.md
└── frontend/
    ├── components.md
    └── styling.md

~/.claude/rules/           # User rules (lower priority)
├── preferences.md
└── workflows.md

Rule with Path Targeting

---
paths:
  - /api/**
  - /src/controllers/**
---

# API Validation Rules

All API endpoints must:
- Validate request payloads
- Return appropriate error messages
- Log validation errors
- Include request ID in responses

MCP (Model Context Protocol)

TLDR: Connect Claude to external tools and APIs. Configure in .mcp.json (project) or ~/.claude.json (user).

Configuration Locations

Schema

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    },
    "remote-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Transport Types

• stdio - Local process (default)
• http - Remote HTTP server
• sse - Server-Sent Events (deprecated)

Tool Naming

MCP tools follow: mcp__<server>__<tool>

• mcp__github__get_issue
• mcp__postgres__query

Management

• /mcp - View servers, authenticate, manage connections

Settings

TLDR: Configure permissions, hooks, environment in settings.json.

Locations (highest to lowest precedence)

1. .claude/settings.local.json - Local project
2. .claude/settings.json - Project (shared)
3. ~/.claude/settings.json - User

Schema

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Read(~/.zshrc)"],
    "deny": ["Bash(curl:*)", "Read(./.env)"],
    "additionalDirectories": ["../docs/"],
    "defaultMode": "default"
  },
  "hooks": {
    "PostToolUse": [...]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "model": "claude-sonnet-4-5-20250929",
  "enableAllProjectMcpServers": true
}

Keyboard Shortcuts

General

Permission Modes (cycle with Shift+Tab)

1. Normal - Standard operation
2. Auto-Accept - Auto-approve edits
3. Plan - Read-only analysis

Multiline Input

Run /terminal-setup to enable Shift+Enter.

Quick Prefixes

Vim Mode

Enable with /vim command.

Quick Reference

File Precedence

Project-level always takes precedence over user-level.

Common Workflows

# Initialize project
claude /init

# Check installation
claude /doctor

# Start in plan mode
claude --permission-mode plan

# Resume previous session
claude /resume