Claude Code CLI

Boot Sequence

What files load when Claude Code starts — and in what order

Progressive disclosure: load only what you need, when you need it

Overview

Boot = Layered Loading

When you run claude, it doesn't load everything at once. It follows a three-phase pattern:

Phase 1 — User Level: Your personal settings and preferences from ~/.claude/

Phase 2 — Project Level: Infrastructure-wide context from ~/projects/CLAUDE.md

Phase 3 — On Demand: Detailed reference files loaded only when a skill or agent needs them

This keeps the initial context small and fast. Claude gets relevant details only when the task calls for them.

Boot Order

The Load Sequence

BOOT START ├─ [1] ~/.claude/settings.json ← global config, MCP servers, permissions ├─ [2] ~/.claude/CLAUDE.md ← user identity, preferences │ ├─ ↳ .claude/docs/agent-docs/CLAUDE.md PM agent context │ ├─ ↳ .claude/docs/agent-docs/inter-agent-protocol.md │ └─ ↳ .claude/skills/CLAUDE.md user skills summary ├─ [3] ~/projects/CLAUDE.md ← master service index │ ├─ ↳ .claude/docs/agent-docs/CLAUDE.md specialist agents │ ├─ ↳ .claude/skills/CLAUDE.md project skills summary │ ├─ ↳ ainotes/SYSTEM-OVERVIEW.md 78 containers, architecture │ └─ ↳ ainotes/directives.md naming, secrets, rules ├─ [ON-DEMAND] ainotes/network.md via network-config skill ├─ [ON-DEMAND] ainotes/security.md via keycloak-setup skill └─ [ON-DEMAND] ainotes/logging.md via logging-observability skill

Phase 1

User-Level Files

Loaded from ~/.claude/ — personal preferences, always first

settings.json boot

~/.claude/settings.json

Global configuration: enables always-thinking mode, MCP server discovery, permission rules. Loaded before anything else.

CLAUDE.md boot

~/.claude/CLAUDE.md

User identity: who you are, your domain, your server. Imports PM agent context, inter-agent protocol, and the user skills summary.

Agents metadata

~/.claude/agents/*.md

Agent names and descriptions are scanned at boot. Full agent content loads only when the agent is invoked via the Task tool.

Skills metadata

~/.claude/skills/*/SKILL.md

Skill names and trigger keywords are scanned at boot. Full SKILL.md content loads only when the skill is invoked by keyword match.

Phase 2

Project-Level Files

Loaded from ~/projects/CLAUDE.md — infrastructure-wide context

Master Index boot

~/projects/CLAUDE.md

The service catalog: 78 running containers, all ports and URLs, routing to individual project CLAUDE.md files on request.

Specialist Agents boot

projects/.claude/docs/agent-docs/CLAUDE.md

Roles and responsibilities for the Architect, Developer, Security, and QA specialist agents. Loaded at boot so Claude understands when to delegate.

System Overview boot

projects/ainotes/SYSTEM-OVERVIEW.md

Current infrastructure state: container count, network topology, service relationships. Gives Claude situational awareness from the first message.

Directives boot

projects/ainotes/directives.md

Non-negotiable rules: naming conventions, secrets storage location, deployment standards, skill invocation rules. Always loaded.

Phase 3

On-Demand Loading

Detailed reference docs — loaded only when the task needs them

Why not load everything at boot?

Context has a cost: larger context = slower responses + higher token usage. Detailed network topology, security policies, and logging configs are only relevant for specific tasks. Loading them on-demand keeps boot fast and focused.

network.md on demand

Docker networks, DNS, topology. Loaded by: network-config, troubleshooting, service-deployment

security.md on demand

Keycloak SSO, OAuth2 policies, firewall rules. Loaded by: keycloak-setup, secrets-security, traefik-setup

logging.md on demand

Loki, Promtail, Grafana config. Loaded by: logging-observability skill only when setting up monitoring.

Summary

Boot in Numbers

CLAUDE.md files
loaded at boot

Agents
discovered

Skills
indexed

Slash commands
available

The key principle: Agents and skills are discovered at boot (names + triggers only), but their full content loads only when invoked. This is progressive disclosure — Claude knows what tools exist without paying the cost of loading all of them upfront.

Claude Code CLI Boot Sequence • ai-servicers.com