Claude Code Architecture Map -- Architecture Guide

01

System Overview

Claude Code is an agentic harness around Anthropic's Claude models. It provides tools, context management, permissions, and an execution environment that turns a language model into a capable coding agent. The system runs locally in a terminal with no build step, connecting to the Anthropic API for model inference.

High-Level Architecture

graph TB
    subgraph User["Developer Environment"]
        TERM["Terminal CLI"]
        VSCODE["VS Code Extension"]
        JETBRAINS["JetBrains Plugin"]
        DESKTOP["Desktop App"]
        WEB["Web / claude.ai"]
    end

    subgraph Core["Claude Code Core"]
        HARNESS["Agentic Harness
(TypeScript / Node.js)"]
        LOOP["Agent Loop
(gather / act / verify)"]
        TOOLS["Tool System
(Read, Edit, Bash...)"]
        PERMS["Permission Engine"]
        CTX["Context Manager"]
        HOOKS["Hooks Engine"]
    end

    subgraph External["External Services"]
        API["Anthropic API
(Claude Models)"]
        MCP_SERVERS["MCP Servers
(stdio / http / sse)"]
        GIT["Git / GitHub"]
        FS["Local Filesystem"]
    end

    TERM --> HARNESS
    VSCODE --> HARNESS
    JETBRAINS --> HARNESS
    DESKTOP --> HARNESS
    WEB --> HARNESS
    HARNESS --> LOOP
    LOOP --> TOOLS
    LOOP --> CTX
    TOOLS --> PERMS
    TOOLS --> FS
    TOOLS --> GIT
    TOOLS --> MCP_SERVERS
    LOOP --> API
    HARNESS --> HOOKS

    style TERM fill:#1e1e28,stroke:#f59e0b,color:#e8e8ee
    style VSCODE fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style JETBRAINS fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style DESKTOP fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style WEB fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style HARNESS fill:#16161e,stroke:#f59e0b,color:#e8e8ee
    style LOOP fill:#16161e,stroke:#d97706,color:#e8e8ee
    style TOOLS fill:#16161e,stroke:#2dd4bf,color:#e8e8ee
    style PERMS fill:#16161e,stroke:#fb7185,color:#e8e8ee
    style CTX fill:#16161e,stroke:#a78bfa,color:#e8e8ee
    style HOOKS fill:#16161e,stroke:#fbbf24,color:#e8e8ee
    style API fill:#16161e,stroke:#f59e0b,color:#e8e8ee
    style MCP_SERVERS fill:#16161e,stroke:#2dd4bf,color:#e8e8ee
    style GIT fill:#16161e,stroke:#4ade80,color:#e8e8ee
    style FS fill:#16161e,stroke:#4ade80,color:#e8e8ee

TypeScript + Node.js

Core runtime built on Node.js 18+. The CLI, agent loop, tool system, and all orchestration logic are TypeScript. Distributed via native installer, Homebrew, WinGet, or npm.

TypeScriptNode.js

Shell + Python

Installation scripts (47% Shell, 29% Python in repo). Cross-platform installers for macOS, Linux, WSL, and Windows. Python for tooling and testing infrastructure.

ShellPython

Claude Models

Powered by Anthropic's Claude model family -- Sonnet for speed, Opus for deep reasoning, Haiku for lightweight subagent tasks. Extended thinking and adaptive reasoning for complex decisions.

SonnetOpusHaiku

Zero Build Step

No compilation required. Works directly in the terminal. GitHub Pages-deployable for the open source repo. Plugin system uses standard JSON and Markdown files.

CLIMCP

02

The Agentic Loop

The core of Claude Code is a three-phase agentic loop: gather context, take action, and verify results. The loop runs continuously until the task is complete, with Claude choosing which tools to invoke at each step based on what it learned from the previous step. The user can interrupt at any point to steer direction.

Agent Loop Lifecycle

graph LR
    USER["User Prompt"] --> GATHER
    GATHER["1. Gather Context
(Read, Grep, Glob, Web)"]
    GATHER --> REASON["Claude Model
(Reasoning + Planning)"]
    REASON --> ACTION["2. Take Action
(Edit, Write, Bash)"]
    ACTION --> VERIFY["3. Verify Results
(Run tests, check output)"]
    VERIFY --> |"Not done"| GATHER
    VERIFY --> |"Complete"| RESULT["Return to User"]
    USER -.-> |"Interrupt"| REASON

    style USER fill:#1e1e28,stroke:#f59e0b,color:#e8e8ee
    style GATHER fill:#16161e,stroke:#60a5fa,color:#e8e8ee
    style REASON fill:#16161e,stroke:#a78bfa,color:#e8e8ee
    style ACTION fill:#16161e,stroke:#2dd4bf,color:#e8e8ee
    style VERIFY fill:#16161e,stroke:#4ade80,color:#e8e8ee
    style RESULT fill:#1e1e28,stroke:#f59e0b,color:#e8e8ee

Gather Context. Claude reads files, searches the codebase with Grep/Glob, fetches web documentation, and explores the project structure. It builds an understanding of the relevant code before acting.
Take Action. Based on its understanding, Claude edits files, creates new files, runs shell commands, or delegates to subagents. Each tool call returns output that feeds into the next reasoning step.
Verify Results. Claude runs tests, checks compiler output, reviews its own changes, and confirms the task is complete. If verification fails, it loops back to gather more context or try a different approach.
Course Correct. The loop is self-healing. Claude chains dozens of tool calls together, adjusting strategy based on errors, test failures, or new information discovered along the way.

Extended Thinking

Claude Code supports extended thinking, giving the model space to reason through complex problems step-by-step before responding. Opus 4.6 uses adaptive reasoning, dynamically allocating thinking tokens based on effort level (low, medium, high). The "ultrathink" keyword forces maximum reasoning depth for a single turn.

Execution Modes

The agent loop operates in several modes depending on context:

Mode	Behavior	Use Case
`Interactive`	Full agentic loop with permission prompts	Normal terminal usage
`Print (-p)`	Single query, outputs response, exits	CI/CD pipelines, scripts
`Plan Mode`	Read-only tools; produces a plan without changes	Complex architectural decisions
`Auto-Accept`	File edits auto-approved; commands still prompt	Trusted iterative coding
`Bypass Perms`	All permission checks skipped	Containers / isolated VMs only

03

Tool System

Tools are what make Claude Code agentic. Without tools, Claude can only respond with text. Each tool use returns information that feeds back into the loop. Tools fall into five categories: file operations, search, execution, web access, and code intelligence.

Tool Categories and Data Flow

graph TD
    MODEL["Claude Model
(tool_use response)"]

    subgraph FileOps["File Operations"]
        READ["Read
(view files, images, PDFs)"]
        EDIT["Edit
(diff-based patches)"]
        WRITE["Write
(create / overwrite)"]
        MV["MultiEdit
(batch operations)"]
    end

    subgraph Search["Search & Discovery"]
        GLOB["Glob
(file pattern matching)"]
        GREP["Grep
(content search, regex)"]
        LS["LS
(directory listing)"]
    end

    subgraph Exec["Execution"]
        BASH["Bash
(shell commands)"]
    end

    subgraph Web["Web Access"]
        FETCH["WebFetch
(URL content)"]
        WSEARCH["WebSearch
(web queries)"]
    end

    subgraph Agent["Orchestration"]
        TASK["Agent
(spawn subagents)"]
        ASK["AskUserQuestion"]
    end

    MODEL --> FileOps
    MODEL --> Search
    MODEL --> Exec
    MODEL --> Web
    MODEL --> Agent

    style MODEL fill:#16161e,stroke:#f59e0b,color:#e8e8ee
    style READ fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style EDIT fill:#1e1e28,stroke:#2dd4bf,color:#e8e8ee
    style WRITE fill:#1e1e28,stroke:#2dd4bf,color:#e8e8ee
    style MV fill:#1e1e28,stroke:#2dd4bf,color:#e8e8ee
    style GLOB fill:#1e1e28,stroke:#a78bfa,color:#e8e8ee
    style GREP fill:#1e1e28,stroke:#a78bfa,color:#e8e8ee
    style LS fill:#1e1e28,stroke:#a78bfa,color:#e8e8ee
    style BASH fill:#1e1e28,stroke:#fb7185,color:#e8e8ee
    style FETCH fill:#1e1e28,stroke:#818cf8,color:#e8e8ee
    style WSEARCH fill:#1e1e28,stroke:#818cf8,color:#e8e8ee
    style TASK fill:#1e1e28,stroke:#fbbf24,color:#e8e8ee
    style ASK fill:#1e1e28,stroke:#fbbf24,color:#e8e8ee

Tool	Permission Level	Description
`Read`	Read-only (no prompt)	View files, images, PDFs, notebooks. Supports line ranges.
`Edit`	File modification (prompts)	Diff-based file patching with before/after matching.
`Write`	File modification (prompts)	Create new files or overwrite existing ones completely.
`MultiEdit`	File modification (prompts)	Batch multiple edits to a single file in one operation.
`Bash`	Command execution (prompts)	Run any shell command. Subject to sandbox restrictions.
`Glob`	Read-only (no prompt)	Find files by glob patterns (e.g. */.ts).
`Grep`	Read-only (no prompt)	Search file contents with regex. Respects .gitignore.
`LS`	Read-only (no prompt)	List directory contents with metadata.
`WebFetch`	Prompts for new domains	Fetch and process web page content.
`WebSearch`	Prompts for new domains	Search the web for information.
`Agent`	Inherits from parent	Spawn subagents with isolated context windows.
`AskUserQuestion`	N/A	Prompt the user for clarification or input.

MCP Tool Search

When many MCP servers are connected, tool definitions can consume significant context. Claude Code automatically enables Tool Search when MCP tool descriptions exceed 10% of the context window, dynamically loading tools on-demand instead of preloading all of them. This keeps the context lean while maintaining access to hundreds of external tools.

04

Subagents

Subagents are specialized AI assistants that run in their own isolated context windows. Each has a custom system prompt, specific tool access, and independent permissions. Claude delegates tasks to subagents to preserve context in the main conversation and enforce constraints.

Subagent Architecture

graph TD
    MAIN["Main Conversation
(Full Context Window)"]

    subgraph Builtin["Built-in Subagents"]
        EXPLORE["Explore
(Haiku, Read-only)"]
        PLAN["Plan
(Inherited Model, Read-only)"]
        GENERAL["General-Purpose
(Inherited Model, All Tools)"]
        BASH_AGENT["Bash Agent
(Inherited Model)"]
    end

    subgraph Custom["Custom Subagents"]
        REVIEW["Code Reviewer
(.claude/agents/)"]
        DEBUG["Debugger
(~/.claude/agents/)"]
        DATA["Data Scientist
(Plugin agents/)"]
    end

    MAIN --> |"delegate"| EXPLORE
    MAIN --> |"delegate"| PLAN
    MAIN --> |"delegate"| GENERAL
    MAIN --> |"delegate"| BASH_AGENT
    MAIN --> |"delegate"| REVIEW
    MAIN --> |"delegate"| DEBUG
    MAIN --> |"delegate"| DATA

    EXPLORE --> |"summary"| MAIN
    PLAN --> |"plan"| MAIN
    GENERAL --> |"result"| MAIN
    BASH_AGENT --> |"output"| MAIN
    REVIEW --> |"feedback"| MAIN
    DEBUG --> |"fix"| MAIN
    DATA --> |"analysis"| MAIN

    style MAIN fill:#16161e,stroke:#f59e0b,color:#e8e8ee
    style EXPLORE fill:#1e1e28,stroke:#22d3ee,color:#e8e8ee
    style PLAN fill:#1e1e28,stroke:#a78bfa,color:#e8e8ee
    style GENERAL fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style BASH_AGENT fill:#1e1e28,stroke:#fb7185,color:#e8e8ee
    style REVIEW fill:#1e1e28,stroke:#4ade80,color:#e8e8ee
    style DEBUG fill:#1e1e28,stroke:#fbbf24,color:#e8e8ee
    style DATA fill:#1e1e28,stroke:#818cf8,color:#e8e8ee

Subagent	Model	Tools	Purpose
`Explore`	Haiku (fast)	Read-only	Quick codebase search and analysis. Thoroughness levels: quick, medium, very thorough.
`Plan`	Inherited	Read-only	Research agent for Plan Mode. Gathers context to formulate implementation plans.
`General-Purpose`	Inherited	All tools	Complex multi-step tasks requiring both exploration and modification.
`Bash`	Inherited	Bash	Running terminal commands in a separate context.
`Custom`	Configurable	Configurable	User-defined via Markdown + YAML frontmatter. Project, user, or plugin scope.

Key Constraint

Subagents cannot spawn other subagents. This prevents infinite nesting. Each subagent runs in complete isolation with its own fresh context window, system prompt, and tool access. Subagents can be run in foreground (blocking) or background (concurrent), and support automatic compaction at ~95% context capacity.

Custom Subagent Configuration

Custom subagents are defined as Markdown files with YAML frontmatter. They can be scoped to a project (.claude/agents/), user (~/.claude/agents/), passed via CLI (--agents JSON flag), or bundled with plugins. Key configuration fields include tools, disallowedTools, model (sonnet/opus/haiku/inherit), permissionMode, hooks, skills, mcpServers, memory scope, and isolation: worktree for git worktree isolation.

05

Context Management

Claude's context window holds conversation history, file contents, command outputs, CLAUDE.md instructions, loaded skills, and system prompts. As work progresses, context fills up. Claude Code manages this automatically through compaction, ensuring the agent can handle long multi-step workflows without losing critical information.

Context Window Layout

graph TD
    subgraph CW["Context Window"]
        SYS["System Prompt
(instructions, tool defs)"]
        CLAUDE_MD["CLAUDE.md Files
(project, user, managed)"]
        RULES["Rules Files
(.claude/rules/*.md)"]
        AUTO_MEM["Auto Memory
(first 200 lines of MEMORY.md)"]
        SKILLS_D["Skill Descriptions
(loaded at start)"]
        MCP_DEFS["MCP Tool Definitions
(all connected servers)"]
        CONV["Conversation History
(messages + tool results)"]
    end

    subgraph Compact["Compaction Pipeline"]
        TRIGGER["Auto-Compact Trigger
(~95% capacity)"]
        CLEAR["Clear Old Tool Outputs"]
        SUMMARIZE["Summarize Conversation"]
        RELOAD["Re-inject CLAUDE.md
(from disk, fresh)"]
    end

    CW --> |"fills up"| TRIGGER
    TRIGGER --> CLEAR
    CLEAR --> SUMMARIZE
    SUMMARIZE --> RELOAD

    style SYS fill:#1e1e28,stroke:#f59e0b,color:#e8e8ee
    style CLAUDE_MD fill:#1e1e28,stroke:#2dd4bf,color:#e8e8ee
    style RULES fill:#1e1e28,stroke:#2dd4bf,color:#e8e8ee
    style AUTO_MEM fill:#1e1e28,stroke:#4ade80,color:#e8e8ee
    style SKILLS_D fill:#1e1e28,stroke:#a78bfa,color:#e8e8ee
    style MCP_DEFS fill:#1e1e28,stroke:#818cf8,color:#e8e8ee
    style CONV fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style TRIGGER fill:#16161e,stroke:#fb7185,color:#e8e8ee
    style CLEAR fill:#16161e,stroke:#fb7185,color:#e8e8ee
    style SUMMARIZE fill:#16161e,stroke:#fb7185,color:#e8e8ee
    style RELOAD fill:#16161e,stroke:#fb7185,color:#e8e8ee

Compaction Strategy

When the context window approaches capacity, Claude Code automatically compacts. Older tool outputs are cleared first, then the conversation is summarized. CLAUDE.md files are always re-read from disk after compaction -- they fully survive the process. Conversation-only instructions that were not written to CLAUDE.md will be lost. The /compact command triggers manual compaction with an optional focus (e.g., /compact focus on the API changes). The auto-compact threshold defaults to ~95% but can be overridden via CLAUDE_AUTOCOMPACT_PCT_OVERRIDE.

Session Persistence

Each conversation is saved locally with full message history. Resume with --continue (most recent) or --resume (by name/picker). Fork with --fork-session to branch without affecting the original.

Sessions

Checkpoints

Before every file edit, Claude Code snapshots the current contents. Press Esc twice to rewind to a previous state. Checkpoints are local to the session, separate from git.

Safety

Skills (On-Demand)

Skills load into context only when invoked, not at startup. This keeps the context lean. Subagents can preload skills via the skills frontmatter field.

Skills

Subagent Isolation

Each subagent gets its own fresh context window. Their work stays isolated, only a summary returns to the main conversation. This prevents context bloat from verbose operations.

Isolation

06

Permission Model

Claude Code uses a tiered permission system that balances power and safety. Read-only tools run without prompts. File modifications and shell commands require approval. Permissions can be configured with allow/deny rules using glob patterns, scoped from organization-wide managed policies down to per-session overrides.

Permission Evaluation Flow

graph TD
    TOOL_CALL["Tool Call
(e.g. Bash, Edit)"]
    PRE_HOOK["PreToolUse Hooks
(optional override)"]
    DENY_CHECK{"Deny Rules?"}
    ASK_CHECK{"Ask Rules?"}
    ALLOW_CHECK{"Allow Rules?"}
    SANDBOX{"Sandbox Check
(OS-level enforcement)"}
    PROMPT["Prompt User
(approve/deny/always)"]
    EXECUTE["Execute Tool"]
    BLOCK["Block Execution"]

    TOOL_CALL --> PRE_HOOK
    PRE_HOOK --> |"hook approves"| EXECUTE
    PRE_HOOK --> |"hook blocks"| BLOCK
    PRE_HOOK --> |"no decision"| DENY_CHECK
    DENY_CHECK --> |"match"| BLOCK
    DENY_CHECK --> |"no match"| ASK_CHECK
    ASK_CHECK --> |"match"| PROMPT
    ASK_CHECK --> |"no match"| ALLOW_CHECK
    ALLOW_CHECK --> |"match"| SANDBOX
    ALLOW_CHECK --> |"no match"| PROMPT
    SANDBOX --> EXECUTE
    PROMPT --> |"approved"| EXECUTE
    PROMPT --> |"denied"| BLOCK

    style TOOL_CALL fill:#1e1e28,stroke:#f59e0b,color:#e8e8ee
    style PRE_HOOK fill:#1e1e28,stroke:#fbbf24,color:#e8e8ee
    style DENY_CHECK fill:#16161e,stroke:#fb7185,color:#e8e8ee
    style ASK_CHECK fill:#16161e,stroke:#818cf8,color:#e8e8ee
    style ALLOW_CHECK fill:#16161e,stroke:#4ade80,color:#e8e8ee
    style SANDBOX fill:#16161e,stroke:#22d3ee,color:#e8e8ee
    style PROMPT fill:#1e1e28,stroke:#a78bfa,color:#e8e8ee
    style EXECUTE fill:#1e1e28,stroke:#4ade80,color:#e8e8ee
    style BLOCK fill:#1e1e28,stroke:#fb7185,color:#e8e8ee

Tool Type	Examples	Approval Required	"Don't Ask Again"
Read-only	Read, Grep, Glob, LS	No	N/A
File modification	Edit, Write, MultiEdit	Yes	Until session end
Bash commands	Shell execution	Yes	Permanently per project + command
Web access	WebFetch, WebSearch	Per new domain	Per domain
MCP tools	External server tools	Per server config	Per server

Settings Precedence

Rules are evaluated in order: deny → ask → allow. The first matching rule wins. Settings cascade from five levels: (1) Managed settings (highest, cannot be overridden), (2) CLI arguments, (3) Local project settings (.claude/settings.local.json), (4) Shared project settings (.claude/settings.json), and (5) User settings (~/.claude/settings.json). If a tool is denied at any level, no other level can allow it.

OS-Level Sandboxing

Beyond the permission system, Claude Code offers native sandboxing using OS-level primitives: Seatbelt on macOS, bubblewrap on Linux/WSL2. The sandbox enforces filesystem isolation (write access restricted to working directory by default) and network isolation (only approved domains via proxy). This provides defense-in-depth against prompt injection -- even if an attacker manipulates Claude's reasoning, the sandbox prevents filesystem and network exfiltration.

07

Hooks System

Hooks are user-defined shell commands, HTTP endpoints, or LLM prompts that execute automatically at specific points in Claude Code's lifecycle. They enable automation, validation, and custom workflows without modifying the core agent.

Hook Lifecycle Events

graph LR
    subgraph Session["Session Lifecycle"]
        INIT["SessionStart"]
        STOP_S["SessionStop"]
    end

    subgraph Instructions["Context Loading"]
        IL["InstructionsLoaded"]
    end

    subgraph Tools["Tool Lifecycle"]
        PRE["PreToolUse
(can approve/deny)"]
        POST["PostToolUse"]
    end

    subgraph Agent["Agent Events"]
        NOTIFY["Notification
(permission, idle, auth)"]
        A_START["SubagentStart"]
        A_STOP["SubagentStop"]
        HALT["Stop"]
    end

    subgraph WT["Worktree"]
        WTC["WorktreeCreate"]
        WTR["WorktreeRemove"]
    end

    INIT --> IL
    IL --> PRE
    PRE --> POST
    POST --> PRE
    POST --> HALT
    HALT --> STOP_S

    style INIT fill:#1e1e28,stroke:#4ade80,color:#e8e8ee
    style STOP_S fill:#1e1e28,stroke:#fb7185,color:#e8e8ee
    style IL fill:#1e1e28,stroke:#a78bfa,color:#e8e8ee
    style PRE fill:#1e1e28,stroke:#f59e0b,color:#e8e8ee
    style POST fill:#1e1e28,stroke:#2dd4bf,color:#e8e8ee
    style NOTIFY fill:#1e1e28,stroke:#818cf8,color:#e8e8ee
    style A_START fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style A_STOP fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style HALT fill:#1e1e28,stroke:#fbbf24,color:#e8e8ee
    style WTC fill:#1e1e28,stroke:#22d3ee,color:#e8e8ee
    style WTR fill:#1e1e28,stroke:#22d3ee,color:#e8e8ee

Event	Matcher Input	Fires When
`SessionStart`	(none)	Session begins
`PreToolUse`	Tool name	Before any tool executes. Exit 2 blocks the call.
`PostToolUse`	Tool name	After a tool completes. Can trigger linting, formatting.
`Notification`	Type string	Claude needs attention (permission, idle, auth).
`SubagentStart/Stop`	Agent name	Subagent begins or completes execution.
`Stop`	(none)	Agent finishes its response.
`InstructionsLoaded`	(none)	CLAUDE.md and rules files are loaded into context.

Hook Types

Hooks can be shell commands (receive JSON on stdin, return decisions via exit codes), HTTP endpoints (POST request with JSON body), or LLM prompts (evaluated by a model). PreToolUse hooks can override the permission system by approving (exit 0) or blocking (exit 2) tool calls. Hooks are configured in settings.json or in subagent frontmatter, and can be scoped with matchers (regex patterns matching tool names or event types).

08

MCP Integration

The Model Context Protocol (MCP) is an open standard for connecting AI tools to external data sources. Claude Code acts as both an MCP client (consuming tools from servers) and can serve as an MCP server itself. MCP enables Claude to query databases, update issue trackers, read design docs, and interact with any API.

MCP Server Topology

graph LR
    CC["Claude Code
(MCP Client)"]

    subgraph Local["Local Servers (stdio)"]
        DB["Database Server
(PostgreSQL, SQLite)"]
        FS_SRV["Filesystem Server"]
        CUSTOM["Custom Script
(npx / python)"]
    end

    subgraph Remote["Remote Servers (HTTP/SSE)"]
        GITHUB["GitHub MCP"]
        SENTRY["Sentry MCP"]
        NOTION["Notion MCP"]
        SLACK_S["Slack MCP"]
        JIRA["Jira MCP"]
    end

    subgraph Managed["Managed / Plugin"]
        PLUGIN_MCP["Plugin MCP Servers
(auto-lifecycle)"]
        MANAGED_MCP["managed-mcp.json
(IT-deployed)"]
    end

    CC --> DB
    CC --> FS_SRV
    CC --> CUSTOM
    CC --> GITHUB
    CC --> SENTRY
    CC --> NOTION
    CC --> SLACK_S
    CC --> JIRA
    CC --> PLUGIN_MCP
    CC --> MANAGED_MCP

    style CC fill:#16161e,stroke:#f59e0b,color:#e8e8ee
    style DB fill:#1e1e28,stroke:#4ade80,color:#e8e8ee
    style FS_SRV fill:#1e1e28,stroke:#4ade80,color:#e8e8ee
    style CUSTOM fill:#1e1e28,stroke:#4ade80,color:#e8e8ee
    style GITHUB fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style SENTRY fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style NOTION fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style SLACK_S fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style JIRA fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style PLUGIN_MCP fill:#1e1e28,stroke:#a78bfa,color:#e8e8ee
    style MANAGED_MCP fill:#1e1e28,stroke:#fb7185,color:#e8e8ee

Three Transports

stdio for local process servers, HTTP (Streamable HTTP, recommended) for cloud services, and SSE (Server-Sent Events, deprecated) for legacy integrations. Configured via claude mcp add.

stdioHTTPSSE

Three Scopes

Local (default, stored in ~/.claude.json per project), Project (shared via .mcp.json in repo), and User (global in ~/.claude.json). Precedence: local > project > user.

Scopes

OAuth 2.0 Auth

Remote HTTP servers support OAuth 2.0 authentication. Tokens are stored securely in the system keychain (macOS) or credentials file. Fixed callback ports and pre-configured credentials supported.

OAuth

Claude as MCP Server

claude mcp serve exposes Claude Code's tools (Read, Edit, LS, etc.) as an MCP server for other applications like Claude Desktop to consume.

Server Mode

Managed MCP Configuration

Organizations can deploy a managed-mcp.json file to system-wide directories for exclusive control over MCP servers, or use allowedMcpServers / deniedMcpServers in managed settings for policy-based restrictions. This enables IT administrators to control which external services Claude Code can access across the organization.

09

Memory System

Claude Code has two complementary memory systems. CLAUDE.md files are instructions you write that are loaded at the start of every session. Auto memory is notes Claude writes itself, capturing learnings like build commands, debugging insights, and code patterns across sessions.

Memory Hierarchy

graph TD
    subgraph Written["Written by You (CLAUDE.md)"]
        MANAGED_MD["Managed Policy
(/Library/.../CLAUDE.md)"]
        PROJECT_MD["Project
(./CLAUDE.md)"]
        USER_MD["User
(~/.claude/CLAUDE.md)"]
        LOCAL_MD["Local
(./CLAUDE.local.md)"]
        RULES["Rules Files
(.claude/rules/*.md)"]
    end

    subgraph Auto["Written by Claude (Auto Memory)"]
        MEMORY_MD["MEMORY.md
(first 200 lines loaded)"]
        TOPIC_FILES["Topic Files
(debugging.md, patterns.md)"]
    end

    subgraph SubMem["Subagent Memory"]
        USER_MEM["User Scope
(~/.claude/agent-memory/)"]
        PROJ_MEM["Project Scope
(.claude/agent-memory/)"]
    end

    MANAGED_MD --> SESSION["Session Context"]
    PROJECT_MD --> SESSION
    USER_MD --> SESSION
    LOCAL_MD --> SESSION
    RULES --> SESSION
    MEMORY_MD --> SESSION
    TOPIC_FILES -.-> |"on demand"| SESSION

    style MANAGED_MD fill:#1e1e28,stroke:#fb7185,color:#e8e8ee
    style PROJECT_MD fill:#1e1e28,stroke:#2dd4bf,color:#e8e8ee
    style USER_MD fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style LOCAL_MD fill:#1e1e28,stroke:#a78bfa,color:#e8e8ee
    style RULES fill:#1e1e28,stroke:#2dd4bf,color:#e8e8ee
    style MEMORY_MD fill:#1e1e28,stroke:#4ade80,color:#e8e8ee
    style TOPIC_FILES fill:#1e1e28,stroke:#4ade80,color:#e8e8ee
    style USER_MEM fill:#1e1e28,stroke:#fbbf24,color:#e8e8ee
    style PROJ_MEM fill:#1e1e28,stroke:#fbbf24,color:#e8e8ee
    style SESSION fill:#16161e,stroke:#f59e0b,color:#e8e8ee

CLAUDE.md Loading

Claude Code walks up the directory tree from the working directory, loading CLAUDE.md and CLAUDE.local.md at each level. Subdirectory CLAUDE.md files load on demand when Claude reads files in those directories. The @path import syntax allows CLAUDE.md files to reference external files (README, package.json, etc.), which are expanded at load time. Maximum import depth is five hops.

Path-Scoped Rules

Rules in .claude/rules/ can be scoped to specific file paths using YAML frontmatter with a paths field supporting glob patterns. For example, a rule with paths: ["src/api/**/*.ts"] only applies when Claude works with files matching that pattern. Rules without a paths field apply unconditionally.

Auto Memory Details

Auto memory is stored at ~/.claude/projects/<project>/memory/. The first 200 lines of MEMORY.md are loaded at the start of every session. Content beyond line 200 is not loaded. Claude keeps MEMORY.md concise by moving detailed notes into separate topic files, which are read on demand. All worktrees within the same git repository share one auto memory directory.

10

Surfaces & Environments

Claude Code runs identically across multiple surfaces -- the agentic loop, tools, and capabilities are the same everywhere. What changes is where the code executes and how you interact with it. All surfaces share CLAUDE.md files, settings, and MCP server configurations.

Execution Environments

graph TB
    subgraph Surfaces["User Interfaces"]
        CLI["Terminal CLI
(full-featured)"]
        VS["VS Code Extension
(inline diffs, @-mentions)"]
        JB["JetBrains Plugin
(interactive diffs)"]
        DESK["Desktop App
(standalone, visual diffs)"]
        WEBUI["Web (claude.ai/code)
(no local setup)"]
        REMOTE["Remote Control
(browser UI, local exec)"]
    end

    subgraph Integrations["CI/CD & Chat"]
        GH_ACTIONS["GitHub Actions
(PR review, triage)"]
        GITLAB["GitLab CI/CD"]
        SLACK_INT["Slack
(@Claude mentions)"]
        CHROME_INT["Chrome Extension
(web debugging)"]
    end

    subgraph Environments["Execution Contexts"]
        LOCAL["Local Machine
(full filesystem access)"]
        CLOUD["Cloud VMs
(Anthropic-managed)"]
        CONTAINER["Containers
(sandboxed, CI)"]
    end

    CLI --> LOCAL
    VS --> LOCAL
    JB --> LOCAL
    DESK --> LOCAL
    WEBUI --> CLOUD
    REMOTE --> LOCAL
    GH_ACTIONS --> CONTAINER
    GITLAB --> CONTAINER
    SLACK_INT --> CLOUD

    style CLI fill:#1e1e28,stroke:#f59e0b,color:#e8e8ee
    style VS fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style JB fill:#1e1e28,stroke:#60a5fa,color:#e8e8ee
    style DESK fill:#1e1e28,stroke:#a78bfa,color:#e8e8ee
    style WEBUI fill:#1e1e28,stroke:#2dd4bf,color:#e8e8ee
    style REMOTE fill:#1e1e28,stroke:#818cf8,color:#e8e8ee
    style GH_ACTIONS fill:#1e1e28,stroke:#4ade80,color:#e8e8ee
    style GITLAB fill:#1e1e28,stroke:#4ade80,color:#e8e8ee
    style SLACK_INT fill:#1e1e28,stroke:#fbbf24,color:#e8e8ee
    style CHROME_INT fill:#1e1e28,stroke:#22d3ee,color:#e8e8ee
    style LOCAL fill:#16161e,stroke:#f59e0b,color:#e8e8ee
    style CLOUD fill:#16161e,stroke:#2dd4bf,color:#e8e8ee
    style CONTAINER fill:#16161e,stroke:#fb7185,color:#e8e8ee

Terminal CLI

The full-featured interface. Edit files, run commands, manage entire projects from the command line. Supports piping (cat file | claude -p), scripting, and Unix composability.

Terminal

IDE Extensions

VS Code and JetBrains plugins provide inline diffs, @-mentions for file context, plan review UI, and conversation history. Same engine, visual diff review.

VS CodeJetBrains

Web & Desktop

Run Claude Code in the browser with no local setup, or use the standalone desktop app for visual diff review. Sessions move between surfaces via /teleport and /desktop.

Cross-Surface

CI/CD & Automation

GitHub Actions and GitLab CI/CD for automated PR review and issue triage. Slack integration for @Claude mentions that produce pull requests. Print mode (-p) for headless scripting.

CI/CDSlack

Plugin System

Claude Code supports plugins that bundle custom skills, subagents, MCP servers, hooks, and commands into distributable packages. Plugins are installed from marketplaces and activated per project. They provide automatic MCP server lifecycle management, agent definitions, and tool extensions without manual configuration.