Claude Code Architecture

Claude Code stores its configuration and data in ~/.claude/. This skill documents the complete structure.

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 at project root.

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 files (zip archives) containing:

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 field is critical - it determines when Claude loads the skill.

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 files that expand to prompts:

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

Project Commands

.claude/commands/ in project root for project-specific 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 or project .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

Create in ~/.claude/skills/skill-name/
Write SKILL.md with frontmatter
Package with package_skill.py

Add global instructions

Edit ~/.claude/CLAUDE.md

Allow a bash command without prompting

Add to ~/.claude/settings.local.json under permissions.allow

Add a custom slash command

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

Configure project-specific behavior

Create .claude/settings.json or ./CLAUDE.md in project root

Subagent System

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

| Type | Purpose | |------|---------| | Explore | Fast codebase exploration, file searches, understanding code | | Plan | Software architecture, implementation planning | | claude-code-guide | Questions about Claude Code itself, features, documentation | | general-purpose | Complex multi-step tasks, research |

Usage: Subagents run autonomously and return results. Use run_in_background: true for parallel execution.

Built-in CLI Commands

| Command | Purpose | |---------|---------| | /help | Show help and available commands | | /clear | Clear conversation history | | /compact | Compress context by summarizing | | /config | Open settings configuration | | /cost | Show token usage and costs | | /doctor | Diagnose issues with setup | | /init | Initialize Claude Code in a project | | /login | Authenticate with Anthropic | | /logout | Sign out | | /mcp | Manage MCP servers | | /memory | View/manage conversation memory | | /model | Switch models (sonnet/opus/haiku) | | /permissions | Manage tool permissions | | /review | Request code review | | /status | Show current session status | | /terminal-setup | Configure terminal integration | | /vim | Toggle vim keybindings | | /tasks | List background 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 or specify in Task tool: model: "haiku"

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

Plan Mode

Entered via EnterPlanMode tool or when planning complex implementations.

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/ tracks all file edits made by Claude.

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/ configuration.

Environment Variables

| Variable | Purpose | |----------|---------| | ANTHROPIC_API_KEY | API authentication | | CLAUDE_CODE_USE_BEDROCK | Use AWS Bedrock backend | | CLAUDE_CODE_USE_VERTEX | Use Google Vertex backend | | CLAUDE_CODE_CONFIG_DIR | Override config directory (default: ~/.claude) | | CLAUDE_CODE_SKIP_HOOKS | Disable hooks temporarily |

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: * matches any characters in that position.

Debug & Troubleshooting

Debug Logs

~/.claude/debug/ contains session debug logs named by session ID.

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 under permissions.allow.

Hook errors: Check hook script exists and is executable. Use /hookify:list to see configured hooks.

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

Diagnostic Command

Run /doctor to check:

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/ stores task lists per session.

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