Claude Code Architecture

Claude Code stores its configuration and data in

~/.claude/

Directory Structure

~/.claude/
├── CLAUDE.md              # Global user instructions (loaded for ALL sessions)
├── settings.json          # Plugin enable/disable state
├── settings.local.json    # Local permissions (allow/deny/ask lists)
├── skills/                # User-installed skills
│   └── *.skill            # Packaged skill files (zip format)
├── plugins/               # Plugin system
│   ├── cache/             # Cached plugin data
│   ├── marketplaces/      # Plugin marketplace mirrors
│   └── installed_plugins.json
├── projects/              # Per-project conversation history
│   └── -path-to-project/  # Directory path encoded with dashes
├── commands/              # Custom slash commands (user-defined)
│   └── *.md               # Slash command definitions
├── history.jsonl          # Command history
├── todos/                 # Task tracking state
├── plans/                 # Plan mode files
├── file-history/          # File edit history/backups
├── debug/                 # Debug logs
└── session-env/           # Session environment state

Configuration Files

CLAUDE.md (Global Instructions)

Location:

~/.claude/CLAUDE.md

Personal instructions loaded into EVERY Claude Code session. Use for:

• Personal coding preferences
• Recurring reminders (e.g., "always use stow for dotfiles")
• Default behaviors

Project-specific instructions go in

./CLAUDE.md

settings.json (Plugin State)

Location:

~/.claude/settings.json

Controls which plugins are enabled:

{
  "enabledPlugins": {
    "plugin-name@marketplace": true
  }
}

settings.local.json (Permissions)

Location:

~/.claude/settings.local.json

Controls tool permissions:

{
  "permissions": {
    "allow": ["Bash(git:*)", "WebSearch"],
    "deny": [],
    "ask": []
  }
}

Permission patterns:

• Bash(command:*)

  - Allow specific bash command patterns

• WebSearch

  - Allow web searches

• Read

  ,

  Write

  ,

  Edit

  - File operation permissions

Skills System

User Skills Location

~/.claude/skills/

Skills are packaged as

.skill

skill-name/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Optional: executable code
├── references/           # Optional: documentation to load as needed
└── assets/               # Optional: templates, images for output

SKILL.md Format

---
name: skill-name
description: What it does and WHEN to trigger it
---

# Skill Name

Instructions and workflow documentation...

The

description

Plugin Skills

Installed from marketplaces to:

• ~/.claude/plugins/cache/{marketplace}/{plugin}/skills/

• ~/.claude/plugins/marketplaces/{marketplace}/skills/

Creating a Skill

Use the skill-creator skill's init script:

python ~/.claude/plugins/marketplaces/anthropic-agent-skills/skills/skill-creator/scripts/init_skill.py <name> --path ~/.claude/skills/

Package with:

python ~/.claude/plugins/marketplaces/anthropic-agent-skills/skills/skill-creator/scripts/package_skill.py ~/.claude/skills/<name>/

Plugin System

Structure

~/.claude/plugins/
├── installed_plugins.json     # Registry of installed plugins
├── known_marketplaces.json    # Available marketplaces
├── cache/                     # Plugin data cache
│   └── {marketplace}/         # Per-marketplace cache
└── marketplaces/              # Marketplace content mirrors
    └── {marketplace}/
        └── skills/            # Skills from this marketplace

Plugin Marketplaces

Default marketplaces:

• anthropic-agent-skills

  - Official Anthropic skills

• claude-plugins-official

  - Official Claude Code plugins

Slash Commands

User Commands Location

~/.claude/commands/

Create

.md

~/.claude/commands/
└── my-command.md    # Invoked as /my-command

Project Commands

.claude/commands/

Hooks

Hooks are shell commands that run in response to Claude Code events. Configure in:

• ~/.claude/settings.json

  (global)

• .claude/settings.json

  (project)

Hook types:

• PreToolUse

  - Before a tool runs

• PostToolUse

  - After a tool runs

• Notification

  - On notifications

• Stop

  - When Claude stops

• SubagentStop

  - When a subagent stops

Use the hookify plugin for easier hook management:

/hookify:help

MCP Servers

MCP (Model Context Protocol) servers extend Claude's capabilities with external tools.

Configure in

~/.claude/settings.json

.claude/settings.json

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {}
    }
  }
}

Project Configuration

Each project can have its own:

• ./CLAUDE.md

  - Project-specific instructions

• .claude/settings.json

  - Project settings and MCP servers

• .claude/commands/

  - Project-specific slash commands

Common Tasks

Add a new skill

1. Create in

   ~/.claude/skills/skill-name/

2. Write

   SKILL.md

   with frontmatter
3. Package with

   package_skill.py

Add global instructions

Edit

~/.claude/CLAUDE.md

Allow a bash command without prompting

Add to

~/.claude/settings.local.json

permissions.allow

Add a custom slash command

Create

~/.claude/commands/command-name.md

Configure project-specific behavior

Create

.claude/settings.json

./CLAUDE.md

Subagent System

The Task tool spawns specialized agents for complex work. Available types:

Explore

Plan

claude-code-guide

general-purpose

Usage: Subagents run autonomously and return results. Use

run_in_background: true

Built-in CLI Commands

/help

/clear

/compact

/config

/cost

/doctor

/init

/login

/logout

/mcp

/memory

/model

/permissions

/review

/status

/terminal-setup

/vim

/tasks

Model Selection

Available models:

• opus - Most capable, best for complex reasoning and planning
• sonnet - Balanced performance and speed (default)
• haiku - Fastest, best for simple tasks, lowest cost

Switch with

/model

model: "haiku"

Use haiku for quick searches/simple edits. Use opus for architecture decisions and complex debugging.

Plan Mode

Entered via

EnterPlanMode

• Plans stored in

  ~/.claude/plans/

• Use for multi-step implementations requiring user approval
• Exit with

  ExitPlanMode

  after user approves plan

File History & Recovery

~/.claude/file-history/

• Each edit creates a versioned backup
• Format:

  {session-id}/{file-hash}@v{version}

• Use to recover from unwanted changes

IDE Integrations

VS Code Extension

• Extension: "Claude Code" in VS Code marketplace
• Provides inline Claude access within editor
• Shares configuration with CLI

JetBrains Plugin

• Available for IntelliJ, PyCharm, WebStorm, etc.
• Integrates with IDE's tool windows

Both connect to the same Claude Code backend and share

~/.claude/

Environment Variables

ANTHROPIC_API_KEY

CLAUDE_CODE_USE_BEDROCK

CLAUDE_CODE_USE_VERTEX

CLAUDE_CODE_CONFIG_DIR

~/.claude

CLAUDE_CODE_SKIP_HOOKS

Permission Pattern Syntax

Patterns in

settings.local.json

"Bash(git:*)"           # Any git command
"Bash(npm run:*)"       # npm run with any script
"Bash(docker:*)"        # Any docker command
"Bash(ls:*)"            # ls with any args
"Bash(cat:*)"           # cat with any args
"Bash(python:*.py)"     # python with .py files
"WebSearch"             # Web search tool
"Read"                  # All file reads (use cautiously)
"mcp__servername__*"    # All tools from an MCP server

Wildcards:

*

Debug & Troubleshooting

Debug Logs

~/.claude/debug/

Common Issues

Skill not loading: Skills load at session start. Restart Claude Code after adding new skills.

Permission denied: Add pattern to

settings.local.json

permissions.allow

Hook errors: Check hook script exists and is executable. Use

/hookify:list

MCP server not connecting: Verify command path, check server logs, ensure dependencies installed.

Diagnostic Command

Run

/doctor

• API key validity
• Configuration file syntax
• MCP server connectivity
• Plugin status

Context & Memory

• Conversations auto-summarize when context grows large
• Per-project history stored in

  ~/.claude/projects/

• /compact

  manually triggers summarization

• /memory

  shows what Claude remembers from summarization

Todo System

~/.claude/todos/

• TodoWrite tool creates/updates tasks
• Tasks persist across conversation turns
• Visible to user in UI as progress indicator