Claude Code Architecture

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

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 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:

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

Built-in CLI Commands

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

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