Claude Code Physiology: How It Actually Works
Mapping the functional pathways of Claude Code — prompt-to-response pipeline, tool execution, hook lifecycle, MCP transport, and failure modes.
Claude Code Physiology
How Claude Code Functions: Flows, Interactions, and Failure Modes
This maps the functional pathways of Claude Code --- how inputs flow to outputs, how components interact, and critically, what happens when things break. This is the causality map: the circulatory, metabolic, and pathological.
Companion piece: the anatomy notebook covers what the parts ARE and where they live. This one covers how they work.
Physiological Systems
| # | System | Metaphor | What It Maps |
|---|---|---|---|
| 1 | Circulation | Prompt to Response pipeline | How user input flows to output |
| 2 | Metabolism | Context window management | Token budget, compression, overflow |
| 3 | Action Potential | Tool execution lifecycle | How a single tool call fires |
| 4 | Reflex Arc | Hook event chain | Stimulus to hook to response |
| 5 | Immune Response | Permission decision tree | Allow/deny cascade |
| 6 | Cell Division | Subagent delegation | When and how work splits |
| 7 | Long-term Potentiation | Memory and learning | What persists, what decays |
| 8 | Pathophysiology | Failure modes and dysfunction | What breaks and why |
Circulation --- The Prompt-to-Response Pipeline
Every interaction follows this flow. Understanding it is understanding Claude Code.
┌─────────────────────────────────────────────────────────────────────────┐
│ PROMPT INTAKE │
│ │
│ User types message │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ CONTEXT ASSEMBLY │ │
│ │ │ │
│ │ 1. System prompt (hard-coded by Anthropic) │ │
│ │ 2. Output style instructions (if configured) │ │
│ │ 3. CLAUDE.md hierarchy (global → project → local) │ │
│ │ 4. Rules (~/.claude/rules/*.md) │ │
│ │ 5. MEMORY.md (first 200 lines) │ │
│ │ 6. Active skill instructions (if matched) │ │
│ │ 7. Loaded MCP tool schemas (from ToolSearch) │ │
│ │ 8. Conversation history (compressed if needed) │ │
│ │ 9. User message + any hook-injected context │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ MODEL INFERENCE │ │
│ │ │ │
│ │ Claude processes assembled context │ │
│ │ Decides: respond with text? call a tool? both? │ │
│ │ │ │
│ │ Model options: │ │
│ │ • Opus 4.6 (claude-opus-4-6) — most capable │ │
│ │ • Sonnet 4.6 (claude-sonnet-4-6) — balanced │ │
│ │ • Haiku 4.5 (claude-haiku-4-5) — fastest │ │
│ │ • Fast mode: same model, faster output │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌──────────────────────────────┐ │
│ │ Text Response │ │ Tool Call(s) │ │
│ │ (streamed to │ │ │ │
│ │ terminal) │ │ → Permission check │ │
│ └─────────────────┘ │ → PreToolUse hooks │ │
│ │ → Tool execution │ │
│ │ → PostToolUse hooks │ │
│ │ → Result back to model │ │
│ │ → Model decides next action │ │
│ └──────────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ STOP DECISION │ │
│ │ │ │
│ │ Model emits stop signal │ │
│ │ Stop hooks fire (can override: exit 2 = "keep going") │ │
│ │ Session continues or ends │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
The key insight: Claude Code is an agentic loop, not a single inference. The model calls tools, gets results, and decides again --- repeatedly --- until it determines the task is complete. A single user message can trigger dozens of tool calls before the model responds with text.
Metabolism --- Context Window Management
The context window is finite. Managing it is metabolic --- what gets absorbed, what gets excreted.
Context Budget
┌───────────────────────────────────────────────┐
│ Total Context Window (~200K tokens) │
│ │
│ ┌───────────────────────────────────────┐ │
│ │ FIXED OVERHEAD (always present) │ │
│ │ │ │
│ │ • System prompt ~2K tokens │ │
│ │ • CLAUDE.md stack ~1-10K │ │
│ │ • Rules ~2-5K │ │
│ │ • MEMORY.md ~1-3K │ │
│ │ • Output style ~1-3K │ │
│ │ • Tool schemas (loaded) ~0.5-5K │ │
│ │ ───────── │ │
│ │ Subtotal: ~7-28K │ │
│ └───────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────┐ │
│ │ CONVERSATION (dynamic, compresses) │ │
│ │ │ │
│ │ • User messages │ │
│ │ • Model responses │ │
│ │ • Tool inputs/outputs │ │
│ │ • File contents (from Read) │ │
│ │ │ │
│ │ Auto-compression kicks in when │ │
│ │ approaching context limit: │ │
│ │ • Older messages summarized │ │
│ │ • Tool outputs truncated │ │
│ │ • File contents replaced with refs │ │
│ └───────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────┐ │
│ │ DEFERRED TOOLS (not in context) │ │
│ │ │ │
│ │ • 500+ MCP tool schemas │ │
│ │ • Only loaded via ToolSearch │ │
│ │ • Critical for window conservation │ │
│ └───────────────────────────────────────┘ │
└───────────────────────────────────────────────┘
Metabolic Pathways
| Process | Trigger | Effect |
|---|---|---|
| Absorption | Read tool, file refs, tool output | Content enters context |
| Compression | Approaching context limit | Old messages summarized |
| Excretion | Context overflow | Oldest messages dropped |
| Deferred loading | ToolSearch call | Tool schema enters context on demand |
Metabolic Disorders
| Disorder | Symptom | Cause |
|---|---|---|
| Context bloat | Slow responses, lost instructions | Too many large file reads |
| Amnesia | Model forgets earlier instructions | Compression removed key context |
| Tool blindness | Model does not use available MCP tools | Tools never loaded via ToolSearch |
| Instruction dilution | CLAUDE.md rules ignored | Too many competing instructions |
Action Potential --- Tool Execution Lifecycle
A single tool call is an action potential: stimulus, threshold, fire, refractory.
┌─────────────────────────────────────────────────────────────────┐
│ TOOL CALL LIFECYCLE │
│ │
│ 1. MODEL DECIDES to call a tool │
│ │ (generates tool_name + tool_input JSON) │
│ │ │
│ 2. PERMISSION CHECK │
│ │ settings.json: allow/deny rules evaluated │
│ │ If denied → tool call blocked, model informed │
│ │ If not in allow list → USER PROMPTED │
│ │ If allowed → proceed │
│ │ │
│ 3. PreToolUse HOOKS FIRE │
│ │ Matcher: does tool_name match hook pattern? │
│ │ Each matching hook runs sequentially │
│ │ Exit 0 → proceed │
│ │ Exit 1 → warning to user, proceed anyway │
│ │ Exit 2 → BLOCK: stderr sent to Claude as feedback │
│ │ Claude sees rejection reason, can adapt │
│ │ │
│ 4. TOOL EXECUTES │
│ │ Built-in: runs internally (Read, Write, Edit, etc.) │
│ │ MCP: request sent to MCP server via stdio/SSE │
│ │ Bash: command executed in sandboxed shell │
│ │ │
│ 5. PostToolUse HOOKS FIRE │
│ │ Receives: tool_name, tool_input, tool_response │
│ │ Cannot block (tool already ran) │
│ │ Use cases: logging, metrics, learning │
│ │ │
│ 6. RESULT RETURNED TO MODEL │
│ │ Tool output enters conversation context │
│ │ Model processes result │
│ │ Decides: another tool call? text response? done? │
│ │ │
│ 7. LOOP or STOP │
│ └→ Back to step 1 (agentic loop continues) │
│ or model emits stop signal │
└─────────────────────────────────────────────────────────────────┘
Parallel vs Sequential Tool Calls
The model can emit multiple tool calls in a single response. Independent calls execute in parallel (for example, reading file A and file B simultaneously). Dependent calls must be sequential (read a file, then edit it). The model is instructed to maximize parallelism for independent operations.
Reflex Arc --- Hook Event Chain
Hooks create reflex arcs --- automatic responses to stimuli that bypass conscious decision-making.
STIMULUS AFFERENT INTEGRATION EFFERENT RESPONSE
(event) (hook input) (script logic) (hook output) (effect)
Tool call made ──────────► JSON stdin ──────────────► Hook script ──────────► Exit code + ──────────► Allow/Block/
{tool_name, evaluates stdout JSON Warn
tool_input} conditions stderr text
Tool completed ──────────► JSON stdin ──────────────► Hook script ──────────► Exit 0 ──────────────► Log/Learn/
{tool_name, processes Persist
tool_response} result
Session starts ──────────► JSON stdin ──────────────► Hook script ──────────► Exit 0 ──────────────► Initialize/
{session_id} bootstraps Prime/Check
Model stops ─────────────► JSON stdin ──────────────► Hook script ──────────► Exit 0 or 2 ─────────► End session
{stop_reason} evaluates or continue
Hook Chaining
When multiple hooks register on the same event, they run sequentially. If any PreToolUse hook exits with code 2, the entire chain stops and the tool is blocked. Exit 0 means proceed. Exit 1 means warn the user but proceed anyway.
PreToolUse[Bash]:
Hook 1 (validate-bash.sh) → exit 0 → proceed to Hook 2
Hook 2 (security-scanner.sh) → exit 0 → proceed to Hook 3
Hook 3 (log-commands.sh) → exit 0 → TOOL EXECUTES
If ANY hook exits 2 → entire chain stops, tool blocked
Reflex vs Voluntary
| Mechanism | Speed | Flexibility | Use Case |
|---|---|---|---|
| Hook (reflex) | Fast (~5s timeout) | Fixed logic | Security gates, logging |
| Prompt hook | Slower (LLM call) | Flexible reasoning | Context-dependent validation |
| Model decision | Slowest | Full reasoning | Complex task planning |
Hooks are faster but rigid. Model decisions are slower but adaptive. The art is knowing which to use where.
Immune Response --- Permission Decision Tree
The permission system is a multi-layered immune defense. Each layer must pass before a tool executes.
Tool Call Arrives
│
▼
┌──────────────────────┐
│ Enterprise Policy │ ← Managed settings (highest authority)
│ deny list? │
│ │
│ YES → BLOCKED │
│ NO → continue ↓ │
└──────────────────────┘
│
▼
┌──────────────────────┐
│ User deny list? │ ← ~/.claude/settings.json
│ │
│ YES → BLOCKED │
│ NO → continue ↓ │
└──────────────────────┘
│
▼
┌──────────────────────┐
│ Project deny list? │ ← .claude/settings.json
│ │
│ YES → BLOCKED │
│ NO → continue ↓ │
└──────────────────────┘
│
▼
┌──────────────────────┐
│ Allow list match? │ ← Any level allow rule
│ │
│ YES → ALLOWED │
│ NO → continue ↓ │
└──────────────────────┘
│
▼
┌──────────────────────┐
│ Permission Mode? │
│ │
│ bypass → ALLOWED │
│ dontAsk → ALLOWED │
│ default → PROMPT ↓ │
│ plan → BLOCKED │
└──────────────────────┘
│
▼
┌──────────────────────┐
│ USER PROMPTED │
│ │
│ "Allow [tool]?" │
│ │
│ Approve → ALLOWED │
│ Deny → BLOCKED │
│ Always → add to │
│ allow list │
└──────────────────────┘
Pattern Matching in Allow/Deny
Permissions use glob-style pattern matching. "Bash" matches all bash commands. "Bash(git:*)" matches only bash commands starting with "git". "mcp__nexcore__*" matches all nexcore MCP tools. "Write(*.test.ts)" matches writes to test files only. This granularity is what makes the immune system precise rather than blunt.
Cell Division --- Subagent Delegation
When a task is too complex or too broad for a single context, the model divides --- spawning subagents.
Division Decision
Task arrives
│
▼
Is the task decomposable into independent subtasks?
│
├── NO → Handle in main context
│
├── YES, 1-2 subtasks → Handle sequentially in main
│
└── YES, 3+ independent subtasks → SPAWN SUBAGENTS
│
▼
┌────────────────────────────────────────┐
│ Main Context │
│ │
│ Agent("subtask A", type="Explore")────┼──► Subagent A (isolated context)
│ Agent("subtask B", type="rust-eng")───┼──► Subagent B (isolated context)
│ Agent("subtask C", type="general")────┼──► Subagent C (isolated context)
│ │
│ ← Results collected │
│ ← Main synthesizes │
└────────────────────────────────────────┘
Context Isolation
The critical thing about subagents: they get an isolated context window. They do NOT inherit the parent conversation, the CLAUDE.md stack, or MEMORY.md. They receive only the system prompt, task description, and agent-specific instructions. This is both their strength (fresh context, no baggage) and their weakness (no shared understanding, no prior conversation).
Main Context Window Subagent Context Window
┌─────────────────────┐ ┌─────────────────────┐
│ Full conversation │ │ System prompt │
│ All loaded tools │ │ Task description │
│ CLAUDE.md stack │ │ Agent instructions │
│ MEMORY.md │ │ Restricted tools │
│ Prior messages │ │ NO parent messages │
│ │ │ NO CLAUDE.md │
│ 200K token window │ │ Own token budget │
└─────────────────────┘ └─────────────────────┘
↕ ↕
Full access Restricted access
Persistent Ephemeral (unless resumed)
Worktree Isolation
For parallel code changes that might conflict in the same working tree, agents can use git worktree isolation. Git creates a temporary branch and working copy, the subagent works in an isolated filesystem, and changes are returned as a branch path when complete. This prevents the deadlock that occurs when two agents try to modify the same file simultaneously.
Long-Term Potentiation --- Memory and Learning
How does Claude Code form persistent memories across sessions?
Memory Formation Pathway
SESSION N SESSION N+1
┌──────────────────────────┐ ┌──────────────────────────┐
│ │ │ │
│ Model observes pattern │ │ Context assembled: │
│ (e.g., user prefers X) │ │ │
│ │ │ │ 1. MEMORY.md loaded │
│ ▼ │ │ (first 200 lines) │
│ Model decides to persist│ │ │
│ │ │ │ 2. Model reads stored │
│ ▼ │ │ patterns + prefs │
│ Edit(MEMORY.md) │ │ │
│ "User prefers X" │───────────────►│ 3. Behavior adjusted │
│ │ │ Persistence │ based on memory │
│ ▼ │ (disk file) │ │
│ Optional: topic files │ │ │
│ for detailed notes │ │ │
│ │ │ │
└──────────────────────────┘ └──────────────────────────┘
What Persists vs What Decays
| Persistence Layer | Survives Across Sessions? | Mechanism |
|---|---|---|
| MEMORY.md (auto-memory) | Yes | File on disk, loaded every session |
| Topic files (memory/*.md) | Yes | Referenced from MEMORY.md |
| Conversation history | No | Lost at session end |
| Tool call results | No | Lost at session end |
| Compressed messages | No | Lost at session end |
| Skill instructions | Yes (but re-matched) | Files on disk, semantically matched |
| Hook state | Depends | Hooks can persist to their own files |
| Agent memory | Yes (if configured) | agent-memory/name/MEMORY.md |
Learning Cycle
Observe → Evaluate → Persist → Retrieve → Apply → Observe...
↑ │ │ │
│ ▼ ▼ │
│ MEMORY.md MEMORY.md │
│ (write) (read) │
└───────────────────────────────────────────────────┘
Memory Capacity Limits
MEMORY.md loads the first 200 lines. Hard truncation beyond that. Topic files have no hard limit but must be referenced from MEMORY.md to be discoverable. The recommended total auto-memory budget is roughly 2% of the context window. There is no automatic pruning --- the model must manually manage stale entries, which creates a slow-burn failure mode when it does not.
Pathophysiology --- Failure Modes and Dysfunction
This is the diagnostic atlas: what breaks, why, and what the symptoms look like. Each pathology maps to a specific anatomical system failure.
┌─────────────────────────────────────────────────────────────────────────┐
│ CLAUDE CODE PATHOPHYSIOLOGY │
│ │
│ SYSTEM PATHOLOGY SYMPTOM │
│ ───────── ───────── ─────── │
│ │
│ Genome ────────────► Config Conflict ────────► Contradictory behavior │
│ (settings) Multiple levels set Tool allowed AND denied │
│ contradictory rules at different levels │
│ │
│ Genome ────────────► CLAUDE.md Overload ─────► Instruction amnesia │
│ (instructions) Too many instructions Model ignores rules │
│ dilute each other buried deep in context │
│ │
│ Skeleton ──────────► Path Mismatch ──────────► "File not found" │
│ (directories) ~/.claude.json vs MCP server won't start │
│ ~/.claude/settings.json Tools unavailable │
│ │
│ Organs ────────────► Tool Misuse ────────────► Inefficient execution │
│ (built-in tools) Using Bash for file ops Slow, unstructured, │
│ instead of Read/Edit hard to review │
│ │
│ Nervous ───────────► MCP Timeout ────────────► Tool call hangs │
│ (MCP servers) Server process crashes Model waits, then fails │
│ or never responds with timeout error │
│ │
│ Nervous ───────────► Tool Blindness ─────────► "I don't have a tool │
│ (deferred tools) ToolSearch never called for that" │
│ Tools exist but unloaded Manual workarounds used │
│ │
│ Muscular ──────────► Skill Mismatch ─────────► Wrong skill fires │
│ (skills) Vague description Irrelevant instructions │
│ matches wrong context loaded into context │
│ │
│ Cellular ──────────► Subagent Starvation ────► Subagent returns │
│ (agents) Insufficient context in incomplete or wrong │
│ task description results │
│ │
│ Cellular ──────────► Context Leak ───────────► Subagent exceeds │
│ (agents) Too many files sent to its context window │
│ subagent (>5 files) Truncation, amnesia │
│ │
│ Immune ────────────► Permission Cascade ─────► Tool permanently │
│ (permissions) User denies once, unavailable │
│ model never retries Workarounds attempted │
│ │
│ Immune ────────────► Over-Permissive ────────► Dangerous commands │
│ (permissions) bypassPermissions mode executed without │
│ with no hooks review │
│ │
│ Endocrine ─────────► Hook Storm ─────────────► Slow startup │
│ (hooks) Too many SessionStart 5+ seconds delay │
│ hooks, each spawning before first response │
│ subprocesses │
│ │
│ Endocrine ─────────► Silent Hook Failure ────► Security gap │
│ (hooks) Hook exits 0 on error Validation bypassed │
│ instead of exit 2 Model proceeds blind │
│ │
│ Endocrine ─────────► Hook-Model Loop ────────► Infinite retry │
│ (hooks) Hook blocks tool (exit 2) Model retries same │
│ Model retries same call call, blocked again │
│ │
│ Memory ────────────► MEMORY.md Bloat ────────► Truncation │
│ (persistence) >200 lines Later entries lost │
│ No pruning discipline Stale info persists │
│ │
│ Memory ────────────► Stale Memory ───────────► Wrong assumptions │
│ (persistence) Old facts never updated Model acts on │
│ Project has changed outdated information │
│ │
│ Metabolism ─────────► Context Exhaustion ─────► Compressed amnesia │
│ (context window) Long session, many reads Model loses early │
│ Context auto-compresses instructions │
│ │
│ Metabolism ─────────► Deferred Starvation ───► Sub-optimal tooling │
│ (tool loading) Model never discovers Uses bash workarounds │
│ MCP tools via ToolSearch instead of typed APIs │
│ │
│ Circulation ────────► Agentic Runaway ───────► Token burn │
│ (prompt pipeline) Model loops: tool call → Expensive session │
│ fail → retry → fail with no progress │
│ No Stop hook intervention │
│ │
│ Circulation ────────► Stop Override Abuse ───► Unending session │
│ (stop decision) Stop hook always exit 2 Model never finishes │
│ "keep going" indefinitely Token waste │
└─────────────────────────────────────────────────────────────────────────┘
Pathological Cascades
When one system fails, it cascades. These are the multi-system failure patterns.
Cascade 1: The Amnesia Spiral
Context exhaustion triggers compression. Compression drops CLAUDE.md rules. The model ignores safety rules it no longer sees. A hook would have caught the violation, but a skill mismatch loads the wrong instructions. The model does the wrong thing confidently.
Context Exhaustion → Compression → CLAUDE.md rules lost → Model ignores
safety rules → Hook would have caught it but... → Skill mismatch loads
wrong instructions → Model does wrong thing confidently
Cascade 2: The Blindness Loop
ToolSearch never gets called. MCP tools remain unavailable. The model uses Bash workarounds. PostToolUse hooks do not fire because they are keyed to the wrong tool name. No logging, no metrics, no learning. The model never discovers the tools exist.
ToolSearch never called → MCP tools unavailable → Model uses Bash
workarounds → PostToolUse hooks don't fire (wrong tool name) → No
logging/metrics → No learning → Model never discovers the tools exist
Cascade 3: The Permission Deadlock
User denies a tool once. The model is told not to retry the exact same call. It tries a slight variation. User denies again. The model gives up. The task is partially complete. Manual intervention required.
User denies tool once → Model told "don't retry exact same call" →
Model tries slight variation → User denies again → Model gives up →
Task partially complete → User frustrated → Manual intervention needed
Cascade 4: The Hook-Model Arms Race
A hook blocks a dangerous pattern with exit 2. The model receives the stderr message. It reformulates the same intent differently. The hook does not catch the new form. The dangerous action proceeds. A PostToolUse hook logs it --- but too late, the action already executed.
Hook blocks dangerous pattern (exit 2) → Model receives stderr →
Model reformulates same intent differently → Hook doesn't catch new
form → Dangerous action proceeds → PostToolUse hook logs it →
But too late, action already executed
Diagnostic Framework
When debugging Claude Code dysfunction, use this decision tree:
Symptom observed
│
├── Model ignores instructions?
│ └── Check: CLAUDE.md hierarchy, context size, compression
│
├── Tool not available?
│ └── Check: MCP config path, ToolSearch usage, server process
│
├── Tool blocked unexpectedly?
│ └── Check: permission rules (all 4 levels), hook exit codes
│
├── Slow/hanging?
│ └── Check: MCP server health, hook timeouts, SessionStart hooks
│
├── Wrong skill loaded?
│ └── Check: skill description specificity, competing skills
│
├── Subagent returns garbage?
│ └── Check: task prompt quality, tool restrictions, file count
│
├── Memory wrong/stale?
│ └── Check: MEMORY.md line count, last update date, topic files
│
└── Infinite loop?
└── Check: hook exit codes, Stop hook logic, permission retries
Summary: The Complete Physiological Map
INPUT PROCESSING OUTPUT
───── ────────── ──────
User prompt ──────────► Context Assembly ──────────► Model Inference
(CLAUDE.md, rules, │
memory, tools, ├──► Text Response
conversation) │
└──► Tool Call(s)
│
┌─────────────┤
│ │
▼ ▼
Permission PreToolUse
Check Hooks
│ │
▼ ▼
┌───────────────────────┐
│ Tool Execution │
│ │
│ Built-in │ MCP │ Bash │
└───────────────────────┘
│
▼
PostToolUse Hooks
│
▼
Result → Model
│
┌─────┴─────┐
│ │
▼ ▼
More tools? Stop?
(loop back) │
▼
Stop Hooks
│
┌─────┴─────┐
│ │
▼ ▼
Exit 0: Exit 2:
Session Keep going
ends (loop back)
Cross-Reference to Anatomy
| Physiology System | Anatomy System | Key Interaction |
|---|---|---|
| Circulation (flow) | All systems | The pipeline that connects everything |
| Metabolism (context) | Genome (config) | Config size affects available context |
| Action Potential (tools) | Organs + Nervous | Built-in + MCP tools fire identically |
| Reflex Arc (hooks) | Endocrine (hooks) | Hooks ARE the reflex anatomy |
| Immune Response (perms) | Immune (perms) | Settings define, runtime enforces |
| Cell Division (agents) | Cellular (agents) | Agent definition leads to agent behavior |
| LTP (memory) | Memory (MEMORY.md) | File structure determines retrieval pattern |
| Pathophysiology | ALL | Every failure traces to an anatomical defect |
Part II: Live Pathology Detectors
The notebook includes executable diagnostic cells that probe a live Claude Code installation for each failure mode from the pathophysiology atlas above. Five detectors test for specific pathologies:
Detector 1: Memory System Disorders
Tests for MEMORY.md bloat (exceeding the 200-line truncation boundary), orphan topic files that exist on disk but are not referenced from MEMORY.md (making them invisible to the model), and stale dates indicating memory has not been updated recently. The 200-line limit is a hard truncation --- anything beyond it is silently dropped during context assembly, meaning the model never sees late entries even though they exist on disk.
Detector 2: Endocrine Disorders (Hook Pathologies)
Tests for hook storms (too many SessionStart hooks adding latency to every session), unwired scripts (hook files on disk but not registered in settings.json, so they never fire), timeout miscalibration (hooks with timeouts too short to complete or so long they block interaction), and non-executable scripts (missing chmod +x, causing silent failures).
Detector 3: Nervous System Disorders (MCP Pathologies)
Tests for MCP config validity, config confusion (mcpServers placed in settings.json instead of .claude.json), missing server binaries, and deferred starvation. Deferred starvation is the ratio of MCP tool calls to total tool calls --- when it drops below 10%, the model is likely using Bash workarounds instead of discovering and using typed MCP tools via ToolSearch.
Detector 4: Circulation Disorders (Session Health)
Tests verdict quality (the ratio of model-authored session verdicts to heuristic-assigned ones), agentic runaway detection (sessions with more than 500 tool calls, indicating the model entered a retry loop), not-demonstrated rate across sessions, and session cadence. The verdict quality metric is particularly diagnostic: when the model rarely produces its own session closeout reflection, the system loses observability into whether sessions actually accomplished their goals.
Vital Signs Dashboard
A composite health score aggregates all four detectors into a single summary. Each system is rated HEALTHY or flagged with issue counts. The composite percentage indicates overall installation health. Priority actions are ranked by impact: memory bloat affects every session through truncation, hook storms affect every session through startup latency, verdict quality affects observability across all sessions, and runaway sessions indicate structural problems in how the model handles failure.
Source: Anthropic Claude Code Documentation and operational experience running 360+ sessions with a production Claude Code installation.