Overview
Episode 2 of the Claude Code Decoded series opens the actual source code and walks through exactly what happens the moment you type claude in your terminal. The startup sequence is more structured than most developers realise — eight distinct stages run before the agentic loop ever sees your first message.
Understanding this sequence matters practically: it explains why certain configurations take priority, how CLAUDE.md files stack, and why MCP servers sometimes fail to initialise correctly.
The 8-Stage Startup Sequence
Stage 1: Argv Parsing
Claude Code is a Node.js binary. When you run claude, Node executes the entry point script and immediately parses the command-line arguments. Flags like --model, --print, --output-format, and --resume are captured here. This stage determines the operating mode before any configuration files are read.
Stage 2: Config Discovery Cascade
Configuration is not a single file — it is a cascade with explicit priority ordering:
- Managed config — enterprise-level settings pushed by an organisation
- User config — your personal settings in the home directory
- Project config — the .claude directory in the project root
- Local config — overrides for the current working directory
Each layer can override the previous. Understanding this cascade is essential for enterprise deployments where you want to enforce certain behaviours while allowing developer flexibility.
Stage 3: CLAUDE.md Loading and Concatenation
Claude Code discovers and concatenates all CLAUDE.md files in scope — from the home directory down through the project hierarchy. These files inject persistent instructions into every conversation. Multiple CLAUDE.md files are merged in order, which means project-level instructions can extend (not just override) global instructions.
Stage 4: MCP Server Boot
MCP (Model Context Protocol) servers are initialised in parallel at startup. Each configured server is launched as a subprocess, and Claude Code waits for them to report readiness before proceeding. If an MCP server fails to boot, Claude Code logs the error but continues — which is why tools from a failed MCP server silently disappear from the available tool set.
Stage 5: Tool Registry Validation
All available tools — built-in tools plus MCP-provided tools — are registered and validated. The registry checks for naming conflicts and ensures tool schemas are valid. This is the stage where the final tool surface is determined for the session.
Stage 6: Permission Mode
Claude Code determines the permission mode for the session — default, auto-approve, or manual. This affects how tool calls are handled: whether they are executed immediately, queued for approval, or blocked. The permission mode can be set via flag, config, or environment variable.
Stage 7: Session Creation
A new session object is created, carrying the conversation state, tool registry, permission mode, and all loaded configuration. This session persists for the lifetime of the Claude Code process.
Stage 8: Agentic Loop Handoff
The session is handed off to the agentic loop — the core engine that manages the conversation, tool execution, and model interactions. Everything before this point was preparation; this is where actual work begins.
Why This Matters for Developers
Knowing the startup sequence lets you debug configuration issues systematically. If a tool is missing, check MCP server boot logs. If configuration is not applying, check the cascade order. If CLAUDE.md instructions are not working, verify the file is in a discoverable path and that a higher-priority config is not overriding it.
Key Takeaways
- Claude Code startup has 8 distinct stages before the agentic loop begins
- Configuration follows a 4-level cascade with explicit priority ordering
- MCP servers boot in parallel — a failed server silently removes its tools from the registry
- CLAUDE.md files from multiple directories are concatenated, not overridden
- Understanding the startup sequence is the foundation for debugging and enterprise configuration
