Claude Code -- Anatomy

Purpose: Map every structural component of Claude Code -- where it lives, what it contains, how it's bounded. This is the boundary map: the skeleton, organs, and membranes.

Companion notebook: claude-physiology.ipynb covers how these parts function together.

Source: Anthropic Claude Code Documentation via Context7 (778 code snippets, High reputation).

Anatomical Systems

Claude Code's files are distributed across multiple locations. There is no single "install directory" -- the architecture is distributed by design.

Configuration Hierarchy (Loading Order)

Claude Code loads configuration from multiple levels, each overriding the previous:

+-----------------------------------------------------------+
|  1. Enterprise Policy (managed settings)                  |  <-- Highest priority
|     /etc/claude-code/settings.json (Linux)                |
|     Enforced by org admins, cannot be overridden          |
+-----------------------------------------------------------+
|  2. User Settings                                         |
|     ~/.claude/settings.json                               |
|     Personal defaults across all projects                 |
+-----------------------------------------------------------+
|  3. Project Settings                                      |
|     .claude/settings.json (in repo root)                  |
|     Committed to git, shared with team                    |
+-----------------------------------------------------------+
|  4. Local Project Settings                                |
|     .claude/settings.local.json (in repo root)            |
|     Gitignored, personal project overrides                |
+-----------------------------------------------------------+

CLAUDE.md Loading Hierarchy

Instructions loaded into every conversation context:

+-----------------------------------------------------------+
|  1. ~/.claude/CLAUDE.md                                   |  <-- Global (all projects)
+-----------------------------------------------------------+
|  2. ~/project-root/CLAUDE.md                              |  <-- Project root
+-----------------------------------------------------------+
|  3. ~/project-root/.claude/CLAUDE.md                      |  <-- Hidden project config
+-----------------------------------------------------------+
|  4. ~/.claude/projects/<hash>/CLAUDE.md                   |  <-- Per-project user notes
+-----------------------------------------------------------+
|  5. Subdirectory CLAUDE.md files                          |  <-- Context-sensitive
|     (loaded when CWD is in that subtree)                  |
+-----------------------------------------------------------+

Key insight: CLAUDE.md files are additive -- they stack, they don't replace.

Core Directory Map

~/.claude/                          # USER-LEVEL Claude Code home
|-- CLAUDE.md                       # Global instructions (always loaded)
|-- settings.json                   # User settings (permissions, hooks, env)
|-- keybindings.json                # Custom keyboard shortcuts
|-- projects/                       # Per-project auto-memory
|   +-- <project-hash>/
|       +-- CLAUDE.md               # Project-specific user notes
|       +-- memory/                 # Auto-memory directory (persistent)
|           +-- MEMORY.md           # Index file (always in context)
|           +-- *.md                # Topic files (referenced from index)
|-- skills/                         # Skill definitions (SKILL.md + scripts)
|   +-- <skill-name>/
|       +-- SKILL.md                # Skill manifest + instructions
|-- agents/                         # Agent definitions
|   +-- <agent-name>.md             # Agent persona + tool restrictions
|-- hooks/                          # Hook scripts
|   +-- bash/                       # Executable hook scripts
|-- rules/                          # Behavioral rules (.md files)
+-- tools/                          # Custom tool binaries (rare)

<project-root>/                     # PROJECT-LEVEL
|-- CLAUDE.md                       # Project instructions (checked in)
|-- .claude/
|   |-- settings.json               # Project settings (checked in)
|   |-- settings.local.json         # Local overrides (gitignored)
|   +-- CLAUDE.md                   # Hidden project instructions
+-- .mcp.json                       # Project MCP server config

MCP Server Configuration

~/.claude.json                      # USER-LEVEL MCP servers (global)
<project>/.mcp.json                 # PROJECT-LEVEL MCP servers
<plugin>/.mcp.json                  # PLUGIN-LEVEL MCP servers

Critical distinction: ~/.claude.json (MCP servers) is not the same as ~/.claude/settings.json (permissions/hooks).

These are Claude Code's native capabilities. Every tool has a typed schema, accepts structured input, and returns structured output.

Primary Tools (Always Available)

Specialized Tools

Tool Anatomy

Every tool call follows this structure:

+--------------+     +--------------+     +--------------+
|  Tool Input  | --> |  Execution   | --> |  Tool Output |
|  (typed JSON)|     |  (sandboxed) |     |  (result)    |
+--------------+     +--------------+     +--------------+
       ^                    ^                     |
       |              Permission                  |
       |              Check                       v
       |              v                    PostToolUse
       +---- PreToolUse Hook              Hook fires
             Hook fires

Source: Anthropic Claude Code docs -- tool schemas are defined at the SDK level, not configurable by users.

Model Context Protocol servers extend Claude Code with external tools. They are the peripheral nervous system -- specialized sensors and effectors beyond the built-in organs.

MCP Server Anatomy

+-----------------------------------------------------------+
|                    Claude Code (Host)                      |
|                                                           |
|   ToolSearch("keyword")                                   |
|        |                                                  |
|        v                                                  |
|   +-------------+    stdio/SSE    +------------------+   |
|   |  Deferred   | <-------------> |  MCP Server      |   |
|   |  Tool Proxy |                 |  (subprocess)    |   |
|   +-------------+                 |                  |   |
|                                   |  +------------+  |   |
|                                   |  | Tool 1     |  |   |
|                                   |  | Tool 2     |  |   |
|                                   |  | Tool N     |  |   |
|                                   |  +------------+  |   |
|                                   +------------------+   |
+-----------------------------------------------------------+

Transport Types

Configuration Structure

// ~/.claude.json (global MCP servers)
{
  "mcpServers": {
    "server-name": {
      "command": "path/to/binary",
      "args": ["--flag", "value"],
      "env": {
        "API_KEY": "..."
      }
    }
  }
}

Tool Loading: Deferred Architecture

All MCP tools are deferred -- they are NOT loaded into context until explicitly discovered:

1. Tools registered in mcpServers config -- server process starts
2. Tool schemas fetched but NOT in conversation context
3. ToolSearch("keyword") -- loads matching tools into active context
4. Tool is now callable for the rest of the conversation

Why deferred? Context window conservation. 500+ tools multiplied by schema size equals significant token cost. Load only what you need.

Source: Anthropic Claude Code documentation -- MCP is based on the open Model Context Protocol specification.

Skills and commands are the executable knowledge -- instructions that Claude Code can invoke on demand.

Skills

A skill is a markdown file (SKILL.md) that contains instructions Claude loads when the task context matches.

~/.claude/skills/<skill-name>/
|-- SKILL.md           # Frontmatter + instructions
|-- scripts/           # Optional helper scripts
+-- references/        # Optional reference docs

Skill Frontmatter (YAML)

---
description: "When to trigger this skill -- Claude matches against this"
trigger: "regex or keyword pattern"
allowed-tools: Read, Write, Edit, Bash
add-dir: ./references    # Additional context directory
---

Activation: Skills are loaded when the task context matches the description field. This is semantic matching -- Claude evaluates whether the current task aligns with the skill's stated purpose.

User-invocable: Some skills can be triggered directly via /skill-name syntax.

Slash Commands

Commands are prompt templates triggered by /command-name:

~/.claude/commands/<command-name>.md    # User-level
<project>/.claude/commands/<name>.md    # Project-level
<plugin>/commands/<name>.md             # Plugin-level

Command Features

Source: Anthropic Claude Code docs -- plugins/plugin-dev/skills/command-development/SKILL.md

Agents are specialized personas with restricted tool access and focused instructions.

Agent Definition

---
identifier: code-reviewer
whenToUse: "Use when reviewing code for quality..."
tools: Read, Glob, Grep          # Tool restrictions
model: claude-sonnet-4-6         # Optional model override
memory: user                     # Persistence mode
---

You are an expert code reviewer...
[Full system prompt]

Agent Frontmatter Fields

Subagent Architecture

+----------------------------------------------+
|              Main Conversation               |
|                                              |
|   Agent("task description",                  |
|         subagent_type="explorer")            |
|        |                                     |
|        v                                     |
|   +------------------------------------+     |
|   |        Subagent Process            |     |
|   |                                    |     |
|   |  - Isolated context window         |     |
|   |  - Own tool access (restricted)    |     |
|   |  - Cannot see parent messages      |     |
|   |  - Returns single result message   |     |
|   |  - Can be resumed by ID            |     |
|   |                                    |     |
|   |  Optional: isolation="worktree"    |     |
|   |  -> Gets own git branch copy       |     |
|   +------------------------------------+     |
|        |                                     |
|        v                                     |
|   Result returned to main conversation       |
+----------------------------------------------+

Built-in Agent Types

Source: Anthropic Claude Code docs -- agent creation system prompt, component lifecycle.

The permission system determines what Claude Code is allowed to do. It operates at multiple boundaries.

Permission Modes

Permission Rules (settings.json)

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(git status)",
      "Bash(cargo build:*)",
      "mcp__nexcore__*"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "WebSearch"
    ]
  }
}

Permission Hierarchy

Enterprise Policy (deny)     <-- Cannot be overridden
       |
       v
User Settings (allow/deny)
       |
       v
Project Settings (allow/deny)
       |
       v
Local Settings (allow/deny)  <-- Lowest priority
       |
       v
Runtime Permission Prompt    <-- User decides in real-time

Deny wins: If ANY level denies a tool, it's denied regardless of allow rules at other levels.

Sandbox

Claude Code can run inside an OS-level sandbox that restricts:

• Network access (domain allowlist)
• File system access (path restrictions)
• Process spawning
• Unix socket connections

{
  "sandbox": {
    "autoAllowBashIfSandboxed": false,
    "network": {
      "allowedDomains": ["api.github.com", "registry.npmjs.org"],
      "allowLocalBinding": false
    },
    "excludedCommands": ["rm", "kill"]
  }
}

Source: Anthropic Claude Code docs -- strict permissions and sandbox settings.

Hooks are event-driven scripts that fire at specific lifecycle moments. They are the hormonal signaling of Claude Code -- broadcasting events system-wide and triggering reflexive responses.

Hook Events

Hook Types

Hook Exit Codes

Exit 0  ->  Allow (tool proceeds / session continues)
Exit 1  ->  Error shown to USER only (tool still proceeds)
Exit 2  ->  BLOCK: stderr shown to Claude, tool call rejected
            (For Stop hooks: exit 2 = "keep going, don't stop")

Hook Configuration (settings.json)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/bash/validate-bash.sh",
            "timeout": 5000
          }
        ]
      }
    ],
    "PostToolUse": [],
    "Stop": [],
    "SessionStart": []
  }
}

Hook I/O Protocol

              stdin (JSON)
                 |
                 v
    +----------------------------+
    |      Hook Script           |
    |                            |
    |  Reads: tool_name,         |
    |         tool_input,        |
    |         tool_response      |
    |                            |
    |  Writes: stdout JSON       |  -> {"decision": "block", "reason": "..."}
    |          stderr text       |  -> Shown to user (exit 1) or Claude (exit 2)
    |                            |
    |  Exit code: 0/1/2          |
    +----------------------------+

Source: Anthropic Claude Code docs -- PreToolUse/PostToolUse hook configuration, hook protocol.

The complete set of configuration surfaces that define Claude Code's behavior.

Configuration File Map

Settings.json Schema (Key Fields)

{
  "permissions": {
    "allow": ["tool patterns"],
    "deny": ["tool patterns"],
    "disableBypassPermissionsMode": "disable"
  },
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [],
    "Stop": [],
    "SessionStart": [],
    "Notification": []
  },
  "env": {
    "KEY": "value"
  },
  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true
}

Plugin Manifest (plugin.json)

Plugins bundle commands, agents, skills, hooks, and MCP servers into a distributable unit:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief explanation of plugin purpose",
  "author": { "name": "Author Name" },
  "commands": "./custom-commands",
  "agents": ["./agents", "./specialized-agents"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./.mcp.json"
}

Source: Anthropic Claude Code docs -- plugin manifest configuration, permission settings.

Claude Code has two memory mechanisms: auto-memory (built-in) and agent memory (per-agent).

Auto-Memory

~/.claude/projects/<project-hash>/memory/
|-- MEMORY.md          # Always loaded into context (first 200 lines)
+-- *.md               # Topic files (referenced from MEMORY.md)

• MEMORY.md is always in context -- every conversation starts with it
• Hard limit: 200 lines loaded (lines beyond truncated)
• The model writes to MEMORY.md via Edit tool when it observes persistent patterns
• Topic files provide overflow -- keep MEMORY.md as a concise index

Agent Memory

Agents with memory: user or memory: project get their own persistent directory:

~/.claude/agent-memory/<agent-name>/
+-- MEMORY.md

What Memory Is NOT

• Not a database (it's flat markdown files)
• Not automatically updated by hooks (the model decides when to write)
• Not shared between conversations (but persists ACROSS conversations)
• Not a session log (that's the brain system -- an extension, not upstream)

+---------------------------------------------------------------+
|                     Claude Code Organism                      |
|                                                               |
|  +----------+  +----------+  +----------+  +----------+      |
|  | Genome   |  | Skeleton |  | Immune   |  | Endocrine|      |
|  | settings |->| dirs &   |->| perms &  |->| hooks &  |      |
|  | configs  |  | files    |  | sandbox  |  | events   |      |
|  +----------+  +----------+  +----------+  +----------+      |
|       |              |              |              |           |
|  +----------+  +----------+  +----------+  +----------+      |
|  | Organs   |  | Nervous  |  | Muscular |  | Cellular |      |
|  | built-in |<-| MCP      |<-| skills & |<-| agents & |      |
|  | tools    |  | servers  |  | commands |  | subagents|      |
|  +----------+  +----------+  +----------+  +----------+      |
|       |                                                       |
|  +----------+                                                 |
|  | Memory   |                                                 |
|  | MEMORY.md|  <-- Persists across sessions                   |
|  +----------+                                                 |
+---------------------------------------------------------------+

Next: See claude-physiology.ipynb for how these systems interact -- the functional pathways, failure modes, and pathophysiology.

Part II: Live Anatomical Probes

Run these cells to measure YOUR Claude Code installation in real time.

Each probe maps to an anatomical system from Part I and produces a measured count, not a memorized claim.

The companion Jupyter notebook (claude-anatomy.ipynb) contains six executable probes:

1. PROBE 1: Skeletal System -- Directory structure census. Counts skills, agents, hook scripts, rules, knowledge files, output styles, memory files, MEMORY.md lines, and Nexcore crates.

2. PROBE 2: Nervous System -- MCP server inventory. Reads ~/.claude.json and enumerates all registered servers with their transport types (stdio vs SSE).

3. PROBE 3: Endocrine System -- Hook registration audit. Reads settings.json and inventories all registered hooks by event type (PreToolUse, PostToolUse, Stop, SessionStart, Notification).

4. PROBE 4: Immune System -- Permission rules audit. Enumerates all allow/deny rules across all settings levels.

5. PROBE 5: Memory System -- Brain and auto-memory census. Measures brain.db state (sessions, artifacts, autopsy records, cumulative tool calls), auto-memory lines, and implicit store health.

6. PROBE 6: Anatomical Atlas -- Visual summary. Generates a radar chart and bar chart showing the relative scale of each anatomical system.

Part III: NexVigilant Augmented Anatomy

Claude Code upstream provides the base organism. NexVigilant has added prosthetic organs -- extensions that don't exist in vanilla Claude Code but are grafted onto the same anatomical surfaces.

UPSTREAM CLAUDE CODE                    NEXVIGILANT AUGMENTATION
-----------------                       --------------------------

Auto-memory (flat .md)        ---->     Brain system (SQLite DB + CLI +
                                        MCP tools + dual-store sync +
                                        autopsy records + implicit learning)

5 hook events                 ---->     54 hook scripts organized as a
                                        "reflex fleet" with lifecycle hooks,
                                        guardian sensors, quality gates,
                                        and session telemetry

Skills (match by description) ---->     219 skills with vocabulary programs,
                                        domain-specific dev references,
                                        and cross-domain transfer engines

Agents (custom subagents)     ---->     65 agents including a full PV
                                        education academy, 5 PV domain
                                        specialists, and a CAIO executive

MCP (tool extensions)         ---->     NexVigilant Station: 112 PV domain
                                        tools across 20 configs, proxying
                                        real FDA/EMA/WHO APIs + deployed
                                        to production for external agents

Permission rules              ---->     15 behavioral rules (diagnostic
                                        conservation, attention-as-energy,
                                        epistemic engagement, etc.) that
                                        function as "cognitive immune system"

Every NexVigilant augmentation must conserve existence = boundary(product(state, void)):

• Boundary: Each augmentation has a clear boundary -- hooks are bash scripts, skills are SKILL.md, agents are .md files
• State: Each augmentation tracks state -- brain.db, implicit stores, MEMORY.md
• Void: Each augmentation fills a void that upstream left empty
• Existence: The augmentation exists because boundary applied to state produces measurable output

Remove any term and the augmentation collapses:

• No boundary: skill with no SKILL.md is invisible to Claude Code
• No state: hook with no persistence means no learning across sessions
• No void: augmentation solving a solved problem is waste